EV10 API Reference

March 25, 2018 | Author: Kieran Coulter | Category: Archive, Application Programming Interface, Trademark, License, Software
Share
Report this link


Comments



Description

Symantec Enterprise Vault™Application Programmer's Guide 10.0 Symantec Enterprise Vault: Application Programmer's Guide The software described in this book is furnished under a license agreement and may be used only in accordance with the terms of the agreement. Last updated: 2012-02-27. Legal Notice Copyright © 2012 Symantec Corporation. All rights reserved. Symantec, the Symantec Logo, Veritas, Enterprise Vault, Compliance Accelerator, and Discovery Accelerator are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners. This Symantec product may contain third party software for which Symantec is required to provide attribution to the third party (“Third Party Programs”). Some of the Third Party Programs are available under open source or free software licenses. The License Agreement accompanying the Software does not alter any rights or obligations you may have under those open source or free software licenses. Please see the Third Party Software file accompanying this Symantec product for more information on the Third Party Programs. The product described in this document is distributed under licenses restricting its use, copying, distribution, and decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior written authorization of Symantec Corporation and its licensors, if any. THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. SYMANTEC CORPORATION SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE. The Licensed Software and Documentation are deemed to be commercial computer software as defined in FAR 12.212 and subject to restricted rights as defined in FAR Section 52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS 227.7202, "Rights in Commercial Computer Software or Commercial Computer Software Documentation", as applicable, and any successor regulations. Any use, modification, reproduction release, performance, display or disclosure of the Licensed Software and Documentation by the U.S. Government shall be solely in accordance with the terms of this Agreement. Symantec Corporation 350 Ellis Street, Mountain View, CA 94043 http://www.symantec.com Technical Support In order to develop software using Enterprise Vault APIs, your company must be a member of Symantec Technology Enabled Program (STEP). For details of the technical support available to you, refer to your STEP membership documentation, or contact the STEP office at [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 .................................................................. 19 Introducing this guide ................................................................... 19 Enterprise Vault documentation ..................................................... 19 Comment on the documentation ..................................................... 19 Chapter 2 API updates .......................................................................... 21 About API updates ....................................................................... Enterprise Vault 10.0.1 ................................................................. Enterprise Vault 10.0 .................................................................... Enterprise Vault 9.0 SP3 ................................................................ Enterprise Vault 9.0 ...................................................................... Enterprise Vault 8.0 SP5 ................................................................ Enterprise Vault 8.0 SP4 ................................................................ Enterprise Vault 8.0 SP3 ................................................................ Enterprise Vault 8.0 SP2 ................................................................ Enterprise Vault 8.0 SP1 ................................................................ Enterprise Vault 8.0 ...................................................................... Minimum supported OS version ................................................ Changes to programming language support ................................ General changes .................................................................... NSF Manager API added .......................................................... Content Management API ........................................................ Retention API ........................................................................ Migration API ........................................................................ New index properties added ..................................................... Corrections ........................................................................... Enterprise Vault 7.0 SP4 ................................................................ Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5 ......................................................................... Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4 ................................................................................. Enterprise Vault 7.0 ...................................................................... 22 22 23 26 26 27 29 30 32 32 34 34 34 34 34 35 38 38 38 39 39 40 42 45 6 Contents Chapter 3 Enterprise Vault API overview .......................................... 47 About API overview ...................................................................... Overview of Enterprise Vault APIs .................................................. Prerequisite software and settings .................................................. Permissions .......................................................................... Licensing .................................................................................... Development licensing ............................................................ Production licensing ............................................................... Deploying an application that uses the API ....................................... Enterprise Vault API runtime MSI ............................................. Checking the API runtime version and the installation path ........... Deploying .NET applications .................................................... Installing the Enterprise Vault SDK ................................................. Checking the SDK version and installation path ........................... SDK examples ....................................................................... Programming notes ...................................................................... Using the Enterprise Vault APIs in C++ ...................................... Using Enterprise Vault APIs in .NET managed languages .............. Using Enterprise Vault APIs in Visual Basic Script ....................... Code samples ........................................................................ Chapter 4 47 47 49 49 50 50 50 51 51 51 53 54 55 55 56 56 56 57 57 Content Management API ................................................. 59 About the Content Management API ................................................ Architecture of Content Management API .................................. General guidelines for using the API ................................................ Use of objects ........................................................................ Enumerating vault stores, archives and items ............................. Saveset IDs and Transaction IDs ............................................... Property validation ................................................................ How Enterprise Vault processes message items ........................... Adding custom index metadata ................................................. Audit logging ........................................................................ Diagnostic logging and tracing ................................................. Enumerations .............................................................................. EV_API_DELETION_LEVEL enumeration .................................... EV_API_EVENT_TYPE enumeration .......................................... EV_API_ITEMS_ORDERBY enumeration .................................... EV_API_TRACE_LEVEL enumeration ......................................... EV_STG_API_ARCHIVE_TYPE enumeration ................................ EV_STG_API_AUTHENTICATE_USING enumeration .................... EV_STG_API_CAN_DELETE enumeration ................................... EV_STG_API_CONVERTED_CONTENT enumeration .................... 65 66 69 69 70 71 71 72 72 74 75 75 75 76 76 76 77 77 78 79 Contents EV_STG_API_CP_SETBY enumeration ....................................... 79 EV_STG_API_CP_UNITS enumeration ....................................... 80 EV_STG_API_DELETION_REASON enumeration ......................... 80 EV_STG_API_EXPIRE_ITEMS enumeration ................................. 81 EV_STG_API_INDEX_LEVEL enumeration .................................. 81 EV_STG_API_INDEX_URGENCY enumeration ............................. 82 EV_STG_API_ITEM_COPYOPTIONS enumeration ........................ 82 EV_STG_API_ITEM_DETAIL enumeration .................................. 83 EV_STG_API_PERMISSIONS_TYPE enumeration ......................... 85 EV_STG_API_STATUS enumeration .......................................... 86 ContentManagementAPI object ...................................................... 87 IContentManagementAPI :: Archive ................................................. 91 IContentManagementAPI :: Item ..................................................... 93 IContentManagementAPI :: Holds ................................................... 94 IContentManagementAPI :: Hold ..................................................... 96 IContentManagementAPI :: DirectoryDNSAlias ................................. 97 IContentManagementAPI :: AuthenticationMode ............................... 99 IContentManagementAPI2 :: VaultStores ........................................ 100 IContentManagementAPI2 :: VaultStore ......................................... 101 IContentManagementAPI2 :: Archives ............................................ 103 IContentManagementAPI3 :: Items ................................................ 103 IContentManagementAPI3 :: IDispatchQueryInterface ...................... 104 IContentManagementAPI4 :: LastError ........................................... 106 VaultStores object ...................................................................... 107 IVaultStores :: Computer .............................................................. 109 VaultStore object ........................................................................ 110 IVaultStore :: Id .......................................................................... 112 IVaultStore :: Name ..................................................................... 113 IVaultStore :: Description ............................................................. 114 IVaultStore :: Status .................................................................... 115 IVaultStore :: ArchiveCount .......................................................... 116 IVaultStore :: DirectoryDNSAlias ................................................... 117 IVaultStore :: Get ........................................................................ 118 Archives object .......................................................................... 119 IArchives :: Computer .................................................................. 122 IArchives :: VaultStoreId .............................................................. 123 IArchives :: ArchiveName ............................................................. 124 IArchives :: Permissions ............................................................... 126 IArchives :: ArchiveTypes ............................................................ 127 Archive object ............................................................................ 128 IArchive :: VaultStoreId ............................................................... 131 IArchive :: Id .............................................................................. 132 IArchive :: Name ......................................................................... 133 7 8 Contents IArchive :: Description ................................................................. IArchive :: ExpireItems ................................................................ IArchive :: ConvertedContent ........................................................ IArchive :: IndexUrgency ............................................................. IArchive :: IndexLevel .................................................................. IArchive :: Size ........................................................................... IArchive :: SecurityDescriptor ....................................................... IArchive :: ComplianceDevice ........................................................ IArchive :: ItemCount .................................................................. IArchive :: Create ........................................................................ IArchive :: Get ............................................................................ IArchive2 :: Type ........................................................................ IArchive2 :: Status ...................................................................... IArchive2 :: HasFolders ................................................................ IArchive2 :: Full .......................................................................... IArchive2 :: DirectoryDNSAlias ..................................................... IArchive3 :: SecurityDescriptor ..................................................... IArchive3 :: SecurityDescriptorString ............................................. IArchive3 :: Type ........................................................................ Items object ............................................................................... IItems :: ArchiveId ...................................................................... IItems :: StartSequenceNum ......................................................... IItems :: OrderBy ........................................................................ Item object ................................................................................ IItem :: ArchiveId ....................................................................... IItem :: Id .................................................................................. IItem :: Content .......................................................................... IItem :: ArchiveMetaData ............................................................. IItem :: BrowserViewURL ............................................................. IItem :: DefaultMSGFormat .......................................................... IItem :: Holds ............................................................................. IItem :: NativeItemURL ................................................................ IItem :: DeletionLevel .................................................................. IItem :: CopyOptions ................................................................... IItem :: Insert ............................................................................. IItem :: Get ................................................................................ IItem :: Delete ............................................................................ IItem :: CanBeDeleted .................................................................. IItem :: CopyTo .......................................................................... IItem :: MoveTo .......................................................................... IItem2 :: DeletionReason .............................................................. IItem3 :: Undelete ....................................................................... Content object ........................................................................... 134 136 138 140 142 143 145 147 148 149 152 153 154 155 156 157 157 159 162 164 168 169 170 172 174 175 177 178 179 181 183 184 185 187 191 194 198 200 201 205 208 210 212 Contents IContent :: Title .......................................................................... IContent :: OriginalLocation ......................................................... IContent :: FileExtension .............................................................. IContent :: MIMEFormat .............................................................. IContent :: CreatedDate ................................................................ IContent :: ModifiedDate .............................................................. IContent :: Data .......................................................................... IContent :: OriginalSize ................................................................ IContent :: Author ....................................................................... ArchiveMetaData object .............................................................. IArchiveMetaData :: RetentionCategory .......................................... IArchiveMetaData :: ComplianceDevice .......................................... IArchiveMetaData :: OverrideOnHoldRetCat .................................... IArchiveMetaData :: ArchivedDate ................................................. IArchiveMetaData :: ComplianceData ............................................. IArchiveMetaData :: SavesetSize ................................................... IArchiveMetaData :: RetentionExpires ............................................ IArchiveMetaData :: IndexData ..................................................... IArchiveMetaData :: IsItemSecured ................................................ IIArchiveMetaData :: CustomIdentifier ........................................... IIArchiveMetaData :: CustomQualifier ............................................ IIArchiveMetaData :: CustomProperties .......................................... IArchiveMetaData :: Update ......................................................... IArchiveMetaData2 :: CurrentLocation ........................................... IArchiveMetaData2 :: CurrentFolderId ............................................ IArchiveMetaData2 :: SequenceNum .............................................. IArchiveMetaData2 :: ArchivedDate ............................................... SimpleIndexMetadata object ........................................................ ISimpleIndexMetadata :: _NewEnum .............................................. ISimpleIndexMetadata :: DateTimesUTC ......................................... ISimpleIndexMetadata :: Count ..................................................... ISimpleIndexMetadata :: Add ........................................................ ISimpleIndexMetadata :: Clear ...................................................... ISimpleIndexMetadata :: ToXML ................................................... ISimpleIndexMetadata :: FromXML ................................................ ISimpleIndexMetadata :: ToLocalTime ............................................ ISimpleIndexMetadata :: ToUTCTime ............................................. SimpleIndexProperty object ......................................................... ISimpleIndexProperty :: Set .......................................................... ISimpleIndexProperty :: Name ...................................................... ISimpleIndexProperty :: Value ...................................................... ISimpleIndexProperty :: Searchable ............................................... ISimpleIndexProperty :: Retrievable ............................................... 214 214 215 217 218 219 220 222 223 225 228 229 230 232 233 234 235 236 237 239 240 242 243 245 251 253 255 256 259 260 261 262 265 265 267 268 269 269 270 272 275 277 278 9 10 Contents ISimpleIndexProperty :: System .................................................... ComplianceData object ................................................................ IComplianceData :: Units ............................................................. IComplianceData :: Value ............................................................. IComplianceData :: SetBy ............................................................. Holds object .............................................................................. IHolds :: _NewEnum .................................................................... IHolds :: Item ............................................................................. IHolds :: Count ........................................................................... IHolds :: GroupId ........................................................................ IHolds :: ConsumerGUID .............................................................. IHolds :: Metadata ....................................................................... IHolds :: Add .............................................................................. IHolds :: PlaceHolds .................................................................... IHolds :: ReleaseHolds ................................................................. IHolds2 :: ReleaseHolds2 .............................................................. Hold object ................................................................................ IHold :: ArchiveId ....................................................................... IHold :: ItemId ............................................................................ IHold :: Id .................................................................................. IHold :: Status ............................................................................ IHold :: Metadata ........................................................................ IHold :: ConsumerGUID ............................................................... IHold :: GroupId ......................................................................... ICollectionBase : IDispatch ........................................................... ICollectionBase :: Count ............................................................... ICollectionBase :: _NewEnum ........................................................ ICollectionBase :: Item ................................................................. ICollectionBase :: Maximum ......................................................... ICollectionBase :: More ................................................................ ICollectionBase :: Get ................................................................... ICollectionBase :: Clear ................................................................ ICollectionBase :: Reset ................................................................ ExtendedErrorInfo object ............................................................. IExtendedErrorInfo :: Error .......................................................... IExtendedErrorInfo :: Description .................................................. IExtendedErrorInfo :: InnerError ................................................... IExtendedErrorInfo :: InnerErrorDescription ................................... IExtendedErrorInfo :: Source ........................................................ DiagnosticsAPI object .................................................................. IDiagnosticsAPI : Name ............................................................... IDiagnosticsAPI : IsTraceEnabled .................................................. IDiagnosticsAPI : LogEvent .......................................................... 279 281 282 283 284 285 287 288 289 290 292 293 294 295 296 298 300 301 302 304 305 306 306 307 308 309 310 311 312 313 314 315 315 316 320 320 321 322 322 323 324 325 325 Contents IDiagnosticsAPI : Trace ............................................................... 326 Chapter 5 NSF Manager API ............................................................... 329 About NSF Manager API .............................................................. NSF Manager API ....................................................................... Components ........................................................................ Security .............................................................................. Enumerations ............................................................................ InitializeNotes enumeration ................................................... NSFManager object ..................................................................... INSFManager :: OpenNSF ............................................................. INSFManager :: CreateNSF ........................................................... INSFManager :: CloseNSF ............................................................. INSFManager :: ViewNote ............................................................ INSFManager :: ImportNote .......................................................... INSFManager :: ExportNote .......................................................... INSFManager :: DeleteNote .......................................................... INSFManager :: InitializeNotes ...................................................... INSFManager :: TerminateNotes ................................................... INSFManager :: SwitchToID .......................................................... Chapter 6 Filtering APIs 329 330 331 331 332 332 332 333 334 335 336 337 338 339 340 341 342 ...................................................................... 345 About the Filtering APIs .............................................................. Exchange Filtering API ................................................................ Developing Exchange external filters ....................................... Exchange filtering registry settings ......................................... Enumerations (Exchange filtering) ................................................ EV_ACTION enumeration ...................................................... EV_ATTACHMENT_ACTION enumeration ................................ EV_RETRY_STATUS enumeration ........................................... EV_REARCHIVE_STATUS enumeration .................................... Message direction enumeration .............................................. IExternalFilter interface .............................................................. IExternalFilter :: Initialize ............................................................ IExternalFilter :: ProcessFilter ...................................................... IExternalFilter :: FilteringComplete ................................................ IArchivingControl interface for Exchange filtering ........................... IArchivingControl :: currentVaultId ............................................... IArchivingControl :: currentRetentionCategoryId ............................. IArchivingControl :: defaultRetentionCategoryId .............................. IArchivingControl :: deleteOriginalItem .......................................... IArchivingControl :: createShortcutToItem ..................................... 348 350 352 352 356 356 356 357 357 358 358 359 359 360 360 365 365 366 367 367 11 12 Contents IArchivingControl :: Action .......................................................... IArchivingControl :: MAPISession .................................................. IArchivingControl :: MAPIMessage ................................................ IArchivingControl :: AddIndexedProperty ....................................... IArchivingControl :: IndexedPropertiesSet ...................................... IArchivingControl :: AddIndexPropertyToSet .................................. IArchivingControl :: AddIndexPropertySet ...................................... IArchivingControl :: TransactionID ................................................ IArchivingControl :: AgentType ..................................................... IArchivingControl :: AgentAssignedRetentionCategoryId ................... IArchivingControl :: AgentAssignedVaultId ..................................... IArchivingControl :: GetFilterProperty ........................................... IArchivingControl :: PutFilterProperty ........................................... IArchivingControl :: AttachmentAction .......................................... IArchivingControl :: RetryStatus ................................................... IArchivingControl :: ReArchiveStatus ............................................. IArchivingControl2 :: BrowserViewURL .......................................... IArchivingControl2 :: NativeItemURL ............................................. IArchivingControl2 :: MessageClass ............................................... IArchivingControl2 :: MAPISaveChanges ........................................ IArchivingControl3 :: SenderRecipientXML ..................................... IArchivingControl3 :: EnvelopeSenderRecipientXML ......................... IArchivingControl3 :: MessageDirection .......................................... IArchivingControl4 :: AddIndexedPropertyEx .................................. Domino Filtering and File System Filtering APIs .............................. About the Domino Filtering API .............................................. About the File System Filtering API ......................................... Developing external filters ..................................................... Domino filtering registry settings ............................................ File System filtering registry settings ....................................... Enumerations (Domino filtering) ................................................... Message direction enumeration .............................................. Domino action enumeration ................................................... Enumerations (File System Filtering) ............................................. File System Archiving action enumeration ................................ IExternalFilter interface .............................................................. IExternalFilter :: Initialize ............................................................ IExternalFilter :: ProcessFilter ...................................................... IExternalFilter :: FilteringComplete ................................................ IExternalFilter :: Shutdown .......................................................... IArchivingControl interface ......................................................... IArchivingControl :: OriginalVaultID .............................................. IArchivingControl :: CurrentVaultID .............................................. 368 368 369 369 370 371 372 373 373 374 374 375 375 376 377 378 378 379 380 381 382 383 385 385 389 389 391 393 394 395 397 397 397 398 398 399 400 400 401 401 402 403 403 Contents IArchivingControl :: OriginalRetentionCategoryID ............................ IArchivingControl :: CurrentRetentionCategoryID ............................ IArchivingControl :: IndexData ..................................................... IArchivingControl :: FilterProperties .............................................. ILotusArchivingControl interface .................................................. ILotusArchivingControl :: Action ................................................... ILotusArchivingControl :: NoteHandle ............................................ ILotusArchivingControl :: DatabaseHandle ...................................... ILotusArchivingControl :: DatabaseName ........................................ ILotusArchivingControl :: SenderRecipientXML ............................... ILotusArchivingControl :: StoreIdentifier ........................................ ILotusArchivingControl :: Direction ............................................... IFileArchivingControl interface .................................................... IFileArchivingControl :: Action ..................................................... IFileArchivingControl :: Name ....................................................... IFileArchivingControl :: Attributes ................................................ IFileArchivingControl :: CreationTimeUtc ....................................... IFileArchivingControl :: LastAccessTimeUtc .................................... IFileArchivingControl :: LastWriteTimeUtc ..................................... IFileArchivingControl :: GetAccessControl ...................................... IFileArchivingControl :: SetAccessControl ....................................... IFileArchivingControl :: Length ..................................................... IFileArchivingControl :: Open ....................................................... IFileArchivingControl :: StreamNames ........................................... IFileArchivingControl :: OpenStream ............................................. IFileArchivingControl :: DeleteStream ............................................ IFileArchivingControl :: ExtendedAttributes .................................... IIndexMetadata interface ............................................................. IIndexMetadata :: ToXML ............................................................. IIndexMetadata :: FromXML ......................................................... IIndexMetadata :: Add ................................................................. IIndexMetadata :: Clear ................................................................ IIndexMetadata :: Count ............................................................... IIndexMetadata :: DateTimesUTC .................................................. IIndexProperty interface ............................................................. IIndexProperty :: Set ................................................................... IIndexProperty :: Name ................................................................ IIndexProperty :: Value ................................................................ IIndexProperty :: Searchable ......................................................... IIndexProperty :: Retrievable ........................................................ IKeyedList interface .................................................................... IKeyedList :: Insert ...................................................................... IKeyedList :: RemoveAt ................................................................ 404 404 405 405 406 406 407 407 407 408 409 410 410 411 412 413 414 415 416 417 417 418 418 420 420 422 423 424 425 425 426 428 428 428 428 430 430 430 431 431 431 432 433 13 ........................................................ About index volumes ............... About storing data in Enterprise Vault .. ISearchQuery :: AddTerm ........... ISearchQuery :: Clear .............. Performing a search ......................................... Using the Search API ............. ESearchQueryOperators enumeration .................................. ISearchQuery :: AddOp ......................... ISearchQuery :: AddProperty ............................................. EPropertySets enumeration .................................. ETruncationReason enumeration ........................................................................................... ESQfilter searches ................................................................................................. ESearchOperatorScope enumeration ................................. ISearchQuery2 :: AddPropertyRange . 435 About Search API ........................... ISearchQuery :: SetRange ............................................................................................................................................................................................................................................................................................................................................................................................................... About indexing options .. Enterprise Vault index properties .......................................................................................................... ISearchQuery :: SetTerm ................... ISearchQuery :: AddRange ..... Granularity of search results .................................................................................................................................................................................................... Constants and enumerations ............. IIndexSearch2 :: IndexVolumeSets ...................................... Introduction to Enterprise Vault indexing ........................................................................................................... ISearchQuery :: SetProperty ......................................................................... Special characters in search queries .............. Constructing a search query ... ESearchQueryFlags enumeration ....... Search API example ................. ISearchQuery :: AddQuery ......... Index Servers and Index Server groups .................. ISearchQuery :: Query ............................. EXMLResultsFormatOptions enumeration ............................................ Index Property constants ....................................................................................................................... SearchQuery object ........................ ISearchQuery2 :: SetPropertyRange ....................................... 438 438 439 439 441 442 443 443 445 446 448 449 449 452 453 453 457 457 458 459 459 460 460 461 461 462 464 465 466 468 470 472 474 476 478 479 481 482 484 485 489 ................ Processing the search results ........................................................................................................................................... ISearchQuery :: Combine ...................................................................................................................................14 Contents Chapter 7 Search API ................................................. IndexSearch object .................................. About index properties ................... EOptionsFlags enumeration ......................................................................................... ............................................................... IIndexVolumeSets :: Item ....................................................... ISearchResults :: Total .................................................................. IIndexVolumeSets :: ArchiveName .............. IIndexVolumeSets :: ArchiveEntryId ........................... ISearchResults :: Results .............................................................................. IIndexVolumeSet :: FirstItemIndexSequenceNumber ................................ IIndexVolumeSets :: Count ................... IIndexSearch2 :: SortBy .............................. IIndexSearch2 :: HasFolders ............... IIndexSearch2 :: ArchiveName ......................... IIndexSearch2 :: AddAdditionalResultsCustomProperty ................................................................................................................. ISearchResults :: Count ......................... IIndexVolumeSets :: HasFolders ............................................................................................................... IIndexSearch2 :: AddAdditionalResultsProperty ....................... IIndexSearch2 :: ArchiveEntryId .............. IndexVolumeSets object ...... IIndexVolumeSet :: ArchiveName ............................................................................ IIndexSearch2 :: MaxSearchIndexVolumeSets ........................................................................................ IIndexVolumeSet :: DateTimesUTC .................... IIndexSearch2 :: SelectArchive ........................................................................ IIndexSearch2 :: ListIndexVolumeSets ................................................ IIndexVolumeSet :: YoungestItemDate ............... IIndexSearch2 :: AdditionalResultsProperties .................. IIndexSearch2 :: IndexVolumeSetCount ............................. IIndexVolumeSet :: YoungestArchivedDate ................................................................................................... IIndexVolumeSets :: _NewEnum .. IIndexSearch2 :: Timeout ................................................................................. IndexVolumeSet object ....... SearchResults object ....................................................................................................... IIndexSearch2 :: Search ........................................................................................ IIndexSearch2 :: MaxSearchResultsPerVolumeSet ............................................................ IIndexSearch2 :: SelectIndexVolume ..................................................... IIndexVolumeSet :: Identity .................................................................................................................. IIndexSearch2 :: SearchToXML .... IIndexSearch2 :: IndexVolumeSetIdentity ................................................................. IIndexVolumeSet :: OldestArchivedDate ...............Contents IIndexSearch2 :: Options .......... 490 491 493 494 495 497 497 498 499 500 501 502 504 505 506 508 510 511 514 517 518 519 519 521 522 522 523 524 525 527 528 529 530 531 531 532 533 534 534 536 538 539 540 15 ... IIndexSearch2 :: SelectIndexVolumeSet .................... IIndexSearch2 :: IndexVolumeIdentity .................................. IIndexVolumeSet :: OldestItemDate ........................................................... IIndexSearch2 :: ResultsPropertySet ................................................................................................ IIndexSearch2 :: Reset ....................................... IIndexVolumeSet :: ArchiveEntryID .................................................................................................. ..................................................16 Contents ISearchResults :: Start ..................... ISearchResults2 :: InSync ................................................................................................................................................................ IRetentionCategories :: Create ........................................... IRetentionCategories :: Lookup ....................... IRetentionCategories2 :: Get ..................... IRetentionCategory :: Identifier .................................. ISearchResult2 :: Item ...................... Enumerations ........ IRetentionCategories :: Item ....................................... IRetentionCategory :: Period .............................................................................. IRetentionCategories :: Update ......................................................................................................................... ISearchResult2 :: DateTimesUTC .................................. IRetentionCategory :: Units ............................................................................................................................................................................................................................. ISearchResults :: _NewEnum ..................................... ISearchResults :: SortBy ...................................... Chapter 8 541 542 543 543 545 546 547 548 549 550 551 552 553 554 556 557 558 Retention API ........................... Retention API ................................... ISearchResults2 :: LoadResults ............................................... 562 562 562 563 563 563 563 564 565 567 568 569 571 572 574 576 577 578 579 581 583 585 587 ......................................................................................................................................................................................................... IRetentionCategories :: Add .............................................. Retention Date Basis enumeration .............................................................................................. IRetentionCategories :: _NewEnum ............................. Security ................. ISearchResults :: Item ............. SearchResult object .............. ISearchResult2 :: Count .. ISearchResults :: Options ............................ ISearchResult :: Prop ..................................... RetentionCategories object ....................................................................................................... ISearchResults2 :: DateTimesUTC ............................................... Retention Units enumeration ................ IRetentionCategories :: Count .............................................................................................................................. RetentionCategory object ............................................................ ISearchResults2 :: TruncationReason .............. IRetentionCategories :: DirectoryDNSAlias .............................. Components ............................................................................................................................................................................. ISearchResult :: Result .. 561 About Retention API ..................................................................................................... IRetentionCategory :: IsVisible ........ ISearchResult :: Prop2 ........................................................ ISearchResult :: Number ............................................................................................................................. IRetentionCategory :: Name ................................. ..................... Note 1 .................................................................. Appendix B 595 596 609 609 610 610 611 612 613 614 615 615 616 616 617 API return values ........ 619 About API return values ................ System properties ........................................... File System filtering ........................................................................ Content Management API return values ........................................ Note 2 ................................................... Note 1 .............................................................................. Appendix A Enterprise Vault properties ........ IRetentionCategory2 :: ExpiryBasis ................ External Filter API Event log messages ........................................... Note 5 ................................................................................................................... Exchange (MAPI) messages .......................... Exchange Server filtering ........................................................................................................................................... How the Enterprise Vault archiving agent processes Exchange mailbox messages ................ 595 About Enterprise Vault properties ................................................................................................................... Defined custom SharePoint properties .................. Note 3 ........................... Retention API return values .................................................. Search API return values ..... Note 4 ..............................................................................................................................................................................................................................................................................................................................Contents IRetentionCategory :: Description ....................... IRetentionCategory :: OnHold ....................................................................................................................................... Domino Server filtering .................................................. Version information ....................... Defined properties for Compliance Accelerator ........ Note 2 .......................................................................... 627 628 628 633 17 ............. 627 About storing and retrieving message items .... IRetentionCategory :: Locked ................................................................. Note 6 ........................ Appendix C 588 589 591 593 619 619 620 621 623 623 624 625 Understanding how Enterprise Vault archives and indexes messages .............................................................................................. How the Content Management API processes Exchange mailbox messages ............................................................................................ Defined custom FSA properties ....................................................................................... Defined custom properties .......................................................... ......................................... How the Content Management API processes Lotus Notes mailbox messages ......................................................................................................................................... 640 640 641 641 645 646 647 648 648 650 650 651 652 Index ......................................................................................................................................................................................................................................................................... SMTP messages ...................................................................... Copying message items ............................ How the Content Management API processes Exchange envelope journal messages . Inter-site copying of archived items ...... How the Enterprise Vault archiving agent processes Lotus Notes journal messages ................................. Why a retrieved item is not a binary copy of the original item ...........18 Contents How the Enterprise Vault archiving agent processes Exchange envelope journal messages ............................................................ Intra-site copying of archived items ......................... How the Content Management API processes SMTP messages ... 653 ............. How the Content Management API processes Lotus Notes journal messages ................................................................................... Lotus Notes messages . How the Enterprise Vault archiving agent processes Lotus Notes mailbox messages ......................................................................... The information in this manual relates to Symantec Enterprise Vault 6. DCOM. in particular. and .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. Comment on the documentation Let us know what you like and dislike about the documentation.0 SP5 and later releases.NET. Readers are assumed to have a good knowledge of Windows application development languages and tools. The Enterprise Vault documentation set is shipped in the Enterprise Vault server kit. 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. Were you able to find the information you needed quickly? Was the information clearly presented? . COM. These enable developers to integrate Enterprise Vault features with third-party applications. C++/C#. com. Please only use this address to comment on product documentation. 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] About this guide Comment on the documentation Report errors and omissions. or tell us what you would find useful in future versions of our guides and online help. We appreciate your feedback. . 0 SP3.0 ■ Enterprise Vault 7.0 SP5 ■ Enterprise Vault 8.0 ■ Enterprise Vault 9.0 ■ Enterprise Vault 8.0 SP2 ■ Enterprise Vault 8. and Enterprise Vault 6.0 SP3 ■ Enterprise Vault 8.0 SP1 ■ Enterprise Vault 8.0 SP4 ■ Enterprise Vault 7. Enterprise Vault 7. and Enterprise Vault 6.0 .0 SP4 ■ Enterprise Vault 2007 SP1.0.0 SP4 ■ Enterprise Vault 8.1 ■ Enterprise Vault 10.0 SP5 ■ Enterprise Vault 2007.Chapter 2 API updates This chapter includes the following topics: ■ About API updates ■ Enterprise Vault 10. Enterprise Vault 7.0 SP3 ■ Enterprise Vault 9.0 SP2. 10788 Exchange Filtering API The IArchivingControl interface of the Exchange Filtering API has been extended to add a new method. The supported range is now 1 January 1970 to 1 January 2038. Items that are indexed with date properties later than 1 January 2038 are also returned in the index search results.1 This section lists the changes and corrections in Enterprise Vault 10. . Table 2-1 Changes and corrections Ref Change details E2595657 Note the following information about dates in Enterprise Vault index properties.0. and AddIndexPropertyToSet.22 API updates About API updates About API updates This chapter lists changes made to the APIs. This enables searching on date-based selection criteria. but the retrieved date values defaults to 1 January 2038. AddIndexPropertySet. Enterprise Vault 10. In index search results. and advance notice of future changes to Enterprise Vault APIs. items that are indexed with date properties earlier than 1 January 1970 are returned in the index search results. Tips and hints about adding custom index properties are provided in the introduction to the Content Management API. See “Adding custom index metadata” on page 72.1. See “IArchivingControl interface for Exchange filtering” on page 360. This method accepts a VARIANT data structure when specifying string. The supported date range in index properties has changed. but the retrieved date values defaults to 1 January 1970. SDK. In previous releases the supported range was 1 January 1970 to 31 December 2148. or this API manual. IArchivingControl4 :: AddIndexedPropertyEx. AddIndexedProperty. Use AddIndexedPropertyEx to add custom index properties instead of the methods.0. integer and date custom index property values. The filters define how the archiving task selects and processes files. To take advantage of the new indexing engine.0 includes a new. see the Enterprise Vault 10. CAS-6002 The File System Filtering API has been added to the Filtering APIs chapter. This API enables you to create external custom filters for File System Archiving tasks. 100-5743. Note: Enterprise Vault 10. Enterprise Vault 10.0 ReadMeFirst. For more details of the indexing engine. Enterprise Vault now runs on 64-bit systems only. This has been fixed. This has been fixed. E2478239 Content Management API Filtering archives by permissions (IArchives :: Permissions) did not return results unless archive types (IArchives::ArchiveTypes) were also specified. If you run Enterprise Vault client application scripts on a 64-bit operating system.0 Table 2-1 Changes and corrections (continued) Ref Change details 9912.API updates Enterprise Vault 10. See “Domino Filtering and File System Filtering APIs” on page 389. 100-6252. Table 2-2 Changes to Filtering APIs Ref Change details 100-2538. 100-5815. 23 . The ReadMe file in the folder InstallFolder\sdk\samples\FSA Filter Sample describes the example filters and gives instructions on how to install and use them. C:\Windows\SysWOW64\cmd. 12266. 100-5024. 100-5049. Two example filters that use the File System Filtering API are included in the SDK.exe.0 This section lists the changes and corrections in Enterprise Vault 10. 64-bit. indexing engine. E2603468 Content Management API A memory leak occurred when IArchive::Get or IArchive::Create were called. use the 32-bit version of command prompt.0. EnterpriseVault.EnterpriseVault.FilterInterfaces. The following search operators are no longer supported for newly indexed items: begins with any of (ESQBeginany) begins with phrase (ESQBegins) is exactly any of (ESQExactany) ends with any of (ESQEndsany) ends with phrase (ESQEnds) automatically add wildcard to end of all words (ESQAutowild) Using these search operators against previously indexed items will continue to be supported. .EnterpriseVault. the class name must include the namespace. 100-6100 Table 2-3 Ref When entering the registry setting value for a file system or Domino custom filter. Changes to Search API Change details Federated searches can be performed across 32-bit and 64-bit indexes for customers upgrading from earlier releases. References in the existing filters to the .FilterInterfaces Note: If you have existing filters developed using the Domino Filtering API.EnterpriseVault.dll. then you need to rebuild the filters after upgrading to Enterprise Vault 10.NET assembly: Symantec.LotusDominoInterfaces.NET assembly. KVS. must be redirected to the new . Indexing service now updates indexes every hour. Symantec.24 API updates Enterprise Vault 10.NET assembly.dll. The separator used between the assembly and the class name must be "!".FilterInterfaces.0 Table 2-2 Changes to Filtering APIs (continued) Ref Change details 100-6002 Filters developed using the Domino Filtering and File System Filtering APIs must reference the .dll The API interfaces are loaded within the namespace: Symantec. In earlier releases this functionality only applied to regular MAPI messages (.API updates Enterprise Vault 10.MsgType custom index properties that are associated with SMTP messages (. 100-6261 If you used the IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier properties to identify an archived item. In this way the scope for identifying the item is limited to the archive.msg files. then full indexing is implemented. 100-5709 In the EV_STG_API_INDEX_LEVEL enumeration. message class "IPM.0 Table 2-3 Changes to Search API (continued) Ref Change details 100-8848 The default timeout value for search requests (IIndexSearch2 :: Timeout) has been changed to 120 (seconds). Enterprise Vault now returns the temporary error. See “IIndexSearch2 :: Timeout” on page 495. 25 . message class "IPM. If medium level indexing is requested on an Enterprise Vault 10.Note. Table 2-4 Changes to Content Management API Ref Change details E2082521 The Enterprise Vault system property. See “Defined custom properties” on page 614.0 servers.SMIME. This could result in ambiguity errors if the properties identified the item in several different archives in the vault store.eml files) and Digitally Signed MAPI messages (. the scope for identifying the item was the vault store. In such circumstances. Enterprise Vault now determines the ArchiveId.msg files.MultipartSigned") are now stored on item insert operations. so that the application can retry the retrieval after a sleep period.Note") that were ingested using the Content Management API. Enterprise Vault reported timeouts and a fatal internal error. They are also preserved when performing copy or move item operations using the Content Management API. is no longer supported. 100-6424 When attempting to retrieve items from slow devices. CONTENTMANAGEMENTAPI_E_BUSY. 100-7987 The sender and recipient indexing metadata and the Vault MsgDirection and Vault. and includes this information when the CustomIdentifier and CustomQualifier properties are used to identify an item. shct.0 server. INDEX_LEVEL_MEDIUM value is not supported on Enterprise Vault 10. and gives instructions on how to install and use it. Table 2-5 Documentation change Ref Change details 100-9330. See “EV_STG_API_CP_SETBY enumeration” on page 79. See “About storing and retrieving message items” on page 627. Enterprise Vault 9. Use the ExtendedErrorInfo object to access detailed error information.0 SP3 This section lists the changes and corrections made for Enterprise Vault 9. but no index locations have been configured for the archive. Enterprise Vault 9.26 API updates Enterprise Vault 9.0 This section lists the changes and corrections made for Enterprise Vault 9.0. ■ ■ Using the Content Management API to migrate Enterprise Vault archived messages from one Enterprise Vault installation to another. ■ Why a retrieved item is not a binary copy of the original item.0 SP3 Table 2-4 Changes to Content Management API (continued) Ref Change details 100-6481 Error reporting has been improved for the situation where an archive is created. Table 2-6 Changes to Content Management API Ref Change details 903-11055 The default value for the enumeration EV_STG_API_CP_SETBY has changed from SETBY_NOTSET to SETBY_RETCAT. how Enterprise Vault processes sender and recipient details for different message types. This appendix provides information on the following topics: How the Content Management API processes message items. In particular. E2365577 A new appendix has been added to this manual. The ReadMe provides a description of the application. and key changes over recent releases of Enterprise Vault. . 100-7796 A new ReadMe file is included with the Content Management API example application (in the folder InstallFolder\samples\ECM API Sample).0 SP3. 0 SP5 This section lists the changes and corrections made for Enterprise Vault 8. Enterprise Vault archives and indexes the item as a file. See “General guidelines for using the API” on page 69.MsgType custom index properties are now stored on item insert operations. These properties are also preserved during copy and move item operations. this method can be used to recover the item. See “IArchive :: Size” on page 143. If an item has been moved to the Enterprise Vault "dumpster" area (soft deleted). either the FileExtension property must have the value ". 2050482 When inserting Outlook messages. or the MIMEFormat property must have the value "application/vnd. 900-1652 Guidance on thread priority has been added. to provide full Enterprise Vault indexing and storage optimization functionality. E2030385 The property type for IArchive::Size was incorrectly shown as ULONGLONG instead of VT_UI8.0 SP5 Table 2-7 Ref Changes to Content Management API Change details MSXML 6. If you assign any other MIME type value to an item. See “IItem :: Insert” on page 191. Table 2-8 Changes to Content Management API Ref Change details 8053386. This has been corrected. See “IContent :: MIMEFormat” on page 217.API updates Enterprise Vault 8.0 or later is now required on the computer where you install the Enterprise Vault API runtime.0 SP5.msg".MsgDirection and Vault. Enterprise Vault 8. 27 . 900-2677 Added the method IItem3::Undelete. and the Vault.ms-outlook". See “IContent :: FileExtension” on page 215. 900-2524 The sender and recipient index properties. See “IItem3 :: Undelete” on page 210. See “Domino filtering registry settings” on page 394.CopiedFrom. Vault. The changes are saved in the archive when the message is subsequently archived. Table 2-9 Changes to Filtering APIs Ref Change details 8054561. now clarify that changes made to messages are saved in the Exchange Server store. See “ISimpleIndexProperty :: Value” on page 275.0 SP5 Table 2-8 Changes to Content Management API (continued) Ref Change details E2133959 ISimpleIndexProperty :: Value now has a fuller description of possible values for the property. E2095734 The remarks in the section. IArchivingControl2 :: MAPISaveChanges. E2096343 HARD_DELETE is now available as an option in the Domino action enumeration. E1980890 The following sections have been expanded to provide more information on the filtering registry settings: See “Exchange filtering registry settings” on page 352. to the list of custom properties defined in Enterprise Vault. .28 API updates Enterprise Vault 8. See “IArchivingControl2 :: MAPISaveChanges” on page 381. See “EV_ACTION enumeration” on page 356. This property provides details for items that have been copied by Move Archive. Table 2-10 Changes to Enterprise Vault properties Ref Change details E2027779 Added the property. See “Defined custom properties” on page 614. API updates Enterprise Vault 8. This has been fixed. This is incorrect. 804-1613.0 SP4 This section lists the changes and corrections made for Enterprise Vault 8. 29 . See “IContent :: FileExtension” on page 215. Table 2-11 Changes to Content Management API Ref Change details E1927661 Updated IContent :: FileExtension section in the manual to clarify the when a preceding period is included in file extensions. 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.0 SP4 Table 2-10 Changes to Enterprise Vault properties (continued) Ref Change details E2139819 The following index properties have been added to the list of Enterprise Vault system properties: ■ Calendar start date (csrt) ■ Calendar end date (cend) ■ Calendar location (clon) ■ Task due date (tddt) ■ Task date completed (tcdt) ■ Task status (tsts) See “System properties” on page 596. The manual has been updated. Enterprise Vault 8. E1533874 The manual indicated that the Vault Store ID must be set before Archive::Get is called. the source item's Sender/Recipients P1 data was not retained and merged with any specified custom index properties for adding to the destination/copied item. E1948433 When using the CopyTo function.0 SP4. See “EV_STG_API_ITEM_DETAIL enumeration” on page 83. See “Items object” on page 164. and provides the property. Table 2-12 Changes to Search API Ref Change details E1448964 Information has been added to the Search API chapter on how to create multiple index volume sets for testing search applications.0 SP3 This section lists the changes and corrections made for Enterprise Vault 8. which enables calling applications to find out why an item was deleted from the archive. has been added to the Content Management API. IItem2. DeletionReason. This interface inherits from IItem. See “Performing a search” on page 449. you can override this limit using the registry setting.0 SP3 Table 2-11 Changes to Content Management API (continued) Ref Change details 8041728. Table 2-13 Changes to Content Management API Ref Change details 803151 A new interface. If required. Enterprise Vault 8. 803137 Soft deleted items are no longer included when populating the Items collection object. See “IItem :: Get” on page 194. then it is not returned in the ‘cont’ property when a call to Item.Get requests DETAIL_LEVEL__SYSTEM_INDEXDATA. E1950563 If the converted content for an item or attachment is larger than 5MB.0 SP3. HKLM\Software\KVS\Enterprise Vault\MaxIndexDataHTMLContentKB The registry setting is documented in the Enterprise Vault Registry Values manual.30 API updates Enterprise Vault 8. See “IItem2 :: DeletionReason” on page 208. . 0. and insufficient resource errors were reported. When retrieving details for pre-Enterprise Vault 7. E1737966 When populating very large Archives collection objects. E1630338 When using the Archive object to retrieve details for an archive that was created prior to Enterprise Vault 7. This has been fixed. 31 . the value of the Maximum property (the maximum number of records that can be returned) was not honored. the ConvertedContent and IndexUrgency properties could contain misleading values. E1726196. This is a success return value. as these properties were introduced at Enterprise Vault 7. 803125. This has been fixed.0. Sometimes files of between 5 MB and 50 MB were truncated when E1739537 retrieved using the Content Management API . When coding in C++ the S_FALSE return value should be handled using the Windows SUCCEEDED or FAILED macros.0 archives.API updates Enterprise Vault 8. 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. 803587. the operation failed. ■ 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.0 SP3 Table 2-13 Ref Changes to Content Management API (continued) Change details 803069. As a result. 0 SP2. 802577. Enterprise Vault 8.0 SP1 This section lists the changes and corrections made for Enterprise Vault 8. . Failure to do this may result in insufficient memory errors when attempting to retrieve large items.0 SP3 API runtime on your client application computer.0 SP1.0 SP2 Table 2-13 Ref Changes to Content Management API (continued) Change details 803327. This has been fixed. IContent::Title no longer needs to be populated before calling Insert. 802559. IArchive::Name and IArchive::Description can contain printable. Enterprise Vault 8. IArchive::Description is optional. 802077 EV_STG_API_AUTHENTICATE_USING enumeration has new value added: AUTHENTICATE_USING_MOST_APPROPRIATE_MODE See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 77. See “IArchive :: Name” on page 133. E1476982. files larger than 50 MB) resulted in corrupt data being returned.32 API updates Enterprise Vault 8. See “IArchive :: Description” on page 134. E1600648 Unicode characters. has been added. See “ExtendedErrorInfo object” on page 316. E1703228. IExtendedErrorInfo. IArchive::Name is mandatory and cannot be blank or an empty string.0 SP2 This section lists the changes and corrections made for Enterprise Vault 8. This interface provides extended error information if an error is encountered when using the Content Management API methods. ensure that you install the Enterprise Vault 8. E1792685 Retrieving large items (that is. Table 2-14 Changes to Content Management API Ref Change details 802168 A new interface. E1639951 See “IItem :: Insert” on page 191.0 SP3 is installed on your Enterprise Vault server. If Enterprise Vault 8. deleting. ■ In addition. This enables additional custom index metadata properties on the source item to be added to existing custom index metadata properties on the destination item. and also returns a summary status report. 8010141 The new interface. See “IHolds2 :: ReleaseHolds2” on page 298. has been added. CopyTo failed and returned the error CONTENTMANAGEMENTAPI_E_BUSY. has been added to the EV_STG_API_ITEM_COPYOPTIONS enumeration. 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. in XML. This has been fixed. 8010204. which can be used to release a hold on each item in a collection.API updates Enterprise Vault 8. 33 . E1422959 If the source archive was in a read-only state. ReleaseHolds2. 8010139 If a hold with the same ConsumerGUID or GroupId was reapplied to an item. ■ Inserting. IHolds2. the IItem::CanBeDeleted property value will indicate DELETE_ACCESS_DENIED for items located in an archive which is in a read-only state. ■ Moving an item when the source or destination archive is in a read-only state.0 SP1 Table 2-15 Changes to Content Management API Ref Change details 8010032 The new value. See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 82. This provides the method. Further changes have been made to support situations where an archive is in a read-only state. ITEM_COPYOPTIONS_MERGE_INDEXMETADATA. or changing the retention period for an item when the archive is in a read-only state. a new hold was created instead of returning the existing hold ID. This has been fixed. for each vault store in which items were processed. Minimum supported OS version The Content Management API features introduced at Enterprise Vault 8. the Visual Basic Script application can perform a QueryInterface using the new IDispatchQueryInterface method and specifying the required Interface Identifier (IID) string.0 This section lists the changes and corrections made for Enterprise Vault 8.msi. .0 The new Content Management API features introduced at Enterprise Vault 8. NSF Manager API added The NSF Manager API enables interaction between Enterprise Vault and Lotus Notes databases.Net programming language. Changes to programming language support Visual Basic 6. Existing Visual Basic 6. are not directly accessible by Visual Basic Script applications. IArchive3 and IArchiveMetaData2. The name of the Enterprise Vault API runtime kit has changed to: Symantec Enterprise Vault API Runtime.0 support third party applications written in the Visual Basic .0 applications that use Content Management API features available in earlier releases of Enterprise Vault are not impacted. The name of the Enterprise Vault SDK kit has changed to Symantec Enterprise Vault Software Development Kit. To access properties on these interfaces. Visual Basic Script The ContentManagement API interfaces.34 API updates Enterprise Vault 8. General changes Audit logging can now be enabled for item operations. but do not support third party applications written in Visual Basic 6.0.0.0 require Windows Server 2003 or later.0 Enterprise Vault 8.msi. See “Audit logging” on page 74. BAU2464 BAU0225 A new interface. SecurityDescriptor and SecurityDescriptorString properties.0 Content Management API Enterprise Vault 8. See “Enumerating vault stores.API updates Enterprise Vault 8.0 includes the following additions and changes to the Content Management API documentation: Table 2-16 Ref Changes to Content Management API 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. has been added to facilitate the enumeration of items in an archive.NET managed code. BAU0819 ■ The EV_STG_API_PERMISSIONS_TYPE enumerator is now used in place of the DV_DS_E_PERMISSION enumerator when creating the security descriptor for use with IArchive::SecurityDescriptor. 35 . BAU0819 ■ IArchive3 interface adds new read/write Type.com/en-us/library/aa379570.microsoft. as described in the Microsoft article: http://msdn. archives and items” on page 70. IItems.aspx This property is recommended for retrieving and setting the security descriptor from applications written in . The SecurityDescriptorString property enables security permissions to be specified using MSDN Security Descriptor String Format. See “IContentManagementAPI3 :: IDispatchQueryInterface” on page 104. See “IItem :: CopyOptions” on page 187. or to be stored. the calling application must run under an account assigned to the Enterprise Vault Power Administrator role or Storage Administrator role. It can be used to identify the start Index Sequence Number when enumerating collections of archived items using the Items collection object. from changing the archived date of an item. See “IArchiveMetaData2 :: CurrentLocation” on page 245.0 Table 2-16 Changes to Content Management API (continued) Ref Change details BAU0778 ■ Significant changes have been made to facilitate copying and moving items from one archive to another : ■ The default action has changed. 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. the item content and its associated ArchiveMetaData and IndexData elements are copied from the source item to the destination item. the calling application can set suitable override values on the destination item object. To prevent unauthorized users. BAU0795 BAU1179 .36 API updates Enterprise Vault 8. BAU778 ■ A new read/write IArchiveMetaData2::ArchivedDate property enables the caller to set the UTC date and time when an item was stored. who have write access to an archive. This means that the new default behaviour preserves the original ArchivedDate and OriginalLocation on the destination item. Note that Windows Server 2003 supports ULONGLONG types with OLE Automation. 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. if override values are not specified. BAU0378 ■ The new IArchiveMetaData2::SequenceNum property (ULONGLONG) uniquely identifies an item in the archive. However ULONGLONG types are not supported on Windows Server 2000 unless an additional component is installed. Override values can be set for specific Item properties. For backwards compatibility. ■ A new CopyOptions property identifies the source item property values to be copied to the destination item when copying or moving items. 0 is now the minimum version of MSXML required on the computer where you install the application using the Content Management API. 37 .NET applications no longer need to call CoInitializeSecurity when remotely accessing IStream or IlockBytes objects containing large items (larger than 4MB).NET applications. BAU1761 ■ IHold::ItemId property value can now be a valid Saveset Id or Transaction Id. BAU1473 ■ The Content Management API now supports IStream and ILockBytes implementations where the input data length provided by the Stat method is not known. which were previously hidden. MSXML 3. thus simplifying use in . BAU1796 ■ BAU2013 ■ BAU2853 Enhancements to the API mean that .API updates Enterprise Vault 8. See “Saveset IDs and Transaction IDs” on page 71. have now been exposed for public use: IArchiveMetaData::CustomIdentifier IArchiveMetaData::CustomQualifier IArchiveMetaData::CustomProperties These properties can be used to hold proprietary information about the stored item. ■ The Content Management API threading model has been changed from COM single-threaded apartment (STA) to Both.0 Table 2-16 Changes to Content Management API (continued) Ref Change details BAU1179 ■ The following properties. CustomIdentifier and CustomQualifier can be used to identify items when using Get. retrievable only . retrievable only Current Retention Category name. retrievable only cllf Current leaf folder name. The migrator must now explicitly set this value. New index properties added Table 2-19 New index properties Ref Index property name Description BAU0585 crct Current Retention Category Id. searchable and retrievable BAU0931 clcn Current location.0 Retention API Table 2-17 Changes to Retention API Ref Change details BAU1072 Enabled the caller to set the date from which storage expiry is calculated. method and property: IRetentionCategories2 Improved the retrieval of retention category details by providing a Get method. Added the following interfaces. ■ IRetentionCategory2 Provides ExpiryBasis property for determining date from which storage expiry is calculated.38 API updates Enterprise Vault 8. retrievable only clfn crcn Current location folder names. and must be unique within the partition. ■ Migration API Table 2-18 Change to Migration API Ref Change details BAU2485 The MigratedFileId parameter of the SendFile method identifies the object or file in the external storage system. API updates Enterprise Vault 7. 847952 The Storage service is no longer accessed when enumerating archives. See “IContent :: FileExtension” on page 215. 39 . and requires the item detail level set to DETAIL_LEVEL_COMPLIANCE_DATA. 1204891 The IContent::OriginalLocation property is now preserved when performing a copy or move operation. See “Archives object” on page 119. retrievable only BAU1426 fpdd Index Fingerprint of item.0 SP4 Table 2-19 New index properties (continued) Ref Index property name Description BAU1320 cnhv Conversation Hierarchical View. 1271036 Description of IArchiveMetaData::RetentionExpires property has been clarified. Table 2-21 Corrections Ref Change details E1107082 Updated description of IContent::FileExtension. searchable and retrievable fpcn Index Fingerprint of content.0 SP4 This section lists the changes and corrections made for Enterprise Vault 7. Enterprise Vault 7.0 SP4. searchable and retrievable Corrections Table 2-20 Corrections Ref Change details 1088101. This property is for use with compliance devices. E1143215 Added description of the use of wildcard characters in ESQfilter searches. E1167957 Updated information about supported combinations of properties in Archives object. E1193018 Updated information about retrieving items. E1188342 Corrected description of IItem :: CanBeDeleted.40 API updates Enterprise Vault 2007 SP1. E1196051 Updated description of ComplianceData object to note that it is for use only with compliance devices. See “ComplianceData object” on page 281.0 SP5 This section lists the changes and corrections made for Enterprise Vault 2007 SP1. Enterprise Vault 2007 SP1.0 SP5 Table 2-21 Corrections (continued) Ref Change details E1185396 Added IContentManagementAPI2 :: VaultStore. See “IItem :: CanBeDeleted” on page 200. Enterprise Vault 7.0 SP3. and added information about retrieving hold data. Enterprise Vault 7. See “ISimpleIndexMetadata :: Count” on page 261. See “IContentManagementAPI2 :: VaultStore” on page 101. and Enterprise Vault 6. and Enterprise Vault 6.0 SP3.0 SP3. in IItem :: Id. See “IArchiveMetaData :: Update” on page 243.0 SP5. E1191078 Added example format for the consumer GUID in IHold :: ConsumerGUID. . See “IItem :: Id” on page 175. See “IHold :: ConsumerGUID” on page 306. Enterprise Vault 7. See “IHolds :: Item” on page 288. and updated Return values for IArchiveMetaData :: Update. E1187820 Corrected description of ISimpleIndexMetadata :: Count. E1203217 Updated Remarks section of IHolds :: Item to note that the index supplied to the property is 1-based not 0-based. and Enterprise Vault 6. 703021. See “ISimpleIndexProperty :: Name” on page 272. recipient details from the Enterprise Vault 2007 SP1 message header (P2) if the archived item is a message. and Enterprise Vault 6. ■ menv index property: This property now includes the message sender/author and delegate sender (if applicable) encoded in the <AUTH> element. This property is now only returned for journaled messages. IArchvingControl3. to retrieve sender and Enterprise Vault 2007 SP1 recipient information as XML.0 SP5. 605047 ■ 751208. This Enterprise Vault 6. See “IArchivingControl interface for Exchange filtering” on page 360. Added new attachment Enterprise Vault 2007 SP1 number ("anum") in the returned index data with the attachment numbering based on the attachment structure as stored in the saveset indexable item data stream. filtering. 703010 ■ Availability New sere index property. 703020. See Table A-1 on page 596.0 SP5. 605036 ■ 751127. SimpleIndexProperty object: Enterprise Vault 7. Enterprise Vault 7. See Table A-1 on page 596. property returns sender and Enterprise Vault 7.0 SP5 Table 2-22 Changes and corrections Ref Change details 751207.API updates Enterprise Vault 2007 SP1. 41 .0 SP3.0 SP3. New interface for Exchange Enterprise Vault 6.0 SP3. It returns sender recipient details from the message envelope (P1) if the archived item is an envelope message. See Table A-1 on page 596. Enterprise Vault 7. ■ menv index property changes.0 SP3. 0 SP3.0 SP2. Now the reason for missing content items is returned in the content missing property (comr) in the index metadata. and Enterprise Vault 6.0 SP4 Table 2-22 Changes and corrections (continued) Ref Change details 751143. content data was unobtainable.0 SP2. Enterprise Vault 7. . where reason was an error code number and type was the item file type. Enterprise Vault 2007 SP1 Enterprise Vault 2007.0 SP4 This section lists the changes and corrections made for Enterprise Vault 2007. "<reason>:<type>". 703011 ■ Availability Previously. E1143932 ■ IArchive::Create: updated description of properties and examples.42 API updates Enterprise Vault 2007. Enterprise Vault 2007 SP1 the cont index metadata property value was returned with a string. Enterprise Vault 7. "1:MSG". Enterprise Vault 7. Enterprise Vault 7. See Table A-1 on page 596.0 SP3. 703038. See “IArchive :: Create” on page 149. For example. and Enterprise Vault 6. and Enterprise Vault 6.0 SP4.0 SP2. where an item's Enterprise Vault 7. vault store Id. Refer to previous releases of the manual for this deprecated API. IArchive2. and Enterprise Vault 6.0 SP4 Table 2-23 Changes and corrections Ref Change details DOR610 ■ DOR620 ■ Availability The following new Content Enterprise Vault 2007 Management API interfaces have been added to enhance enumeration of archives and vault stores: IContentManagementAPI2. retention category Id. IArchives. This will be incorporated in the Utilities Guide at a future release. ■ DirectoryDNSAlias property in the Content Management API and Retention API has been enhanced to accept input of any Enterprise Vault id. ICollectionBase. archive Id. ■ Integrating third-party messaging removed and now available as a tech note from Enterprise Vault support knowledge base. ■ Migration API included in API Guide. IVaultStores. such as. ■ Provisioning API removed. Simple API removed from API Enterprise Vault 2007 Guide. ■ New IDiagnosticsAPI interface added to Content Management API to enable application integration tracing using Enterprise Vault diagnostic tools. These interfaces supersede the functionality previously provided by the unsupported EnumVaultsByMe method.API updates Enterprise Vault 2007. Enterprise Vault 7. 43 .0 SP2. IVaultStore. 0 is required for this feature. DETAIL_LEVEL_ITEM_CONTENT.0 SP4. you could Enterprise Vault 6. and Enterprise Vault 6.0 SP2. See “ISimpleIndexProperty :: Name” on page 272. Enterprise Vault 7. The menv index property is described. Enterprise Vault 7. See Table A-1 on page 596.2 and so on). the current date and time was returned by IContent::ModifiedDate and IContent::CreatedDate.0 SP2 distribution list information from the XMLStream using the Content Management API. 1. not retrieve expanded Enterprise Vault 7. IItem::Get().0 SP2 was included as part of the input parameter for the Content Management API method. 604133 ■ Availability When the enumerated value. Enterprise Vault 6.44 API updates Enterprise Vault 2007. ■ The value of ISimpleIndexProperty :: Name can now be a formatted number (1.1. This has been fixed. See “EV_STG_API_ITEM_DETAIL enumeration” on page 83. . 1. which refers to a message attachment. Note that MSXML 4.0 SP4. E974294 ■ 702045. 604133.0 SP4 Table 2-23 Changes and corrections (continued) Ref Change details 702045. It is retrieved in the menv index property using the DETAIL_LEVEL_MESSAGE_ ENVELOPE_INDEXDATA value of the EV_STG_API_ITEM_ DETAIL enumeration. This information can now be accessed using the existing IArchiveMetaData :: IndexData property. In previous releases. 0 Enterprise Vault 7.0 added to Exchange Server Filtering API.API updates Enterprise Vault 7. if an item Enterprise Vault 7. Enterprise Vault 7. CAP545.0. CAP721. CAP525 ■ IContentManagementAPI has Enterprise Vault 7. then it could not be deleted.0 This section lists the changes and corrections made for Enterprise Vault 7. which have been moved from IArchivingControl.0 CAP463 ■ In previous releases.0 had been marked "on hold" using the retention category.0 a new property: AuthenticationMode. BrowserViewURL and NativeViewURL. This has been fixed.0 CAP433 ■ An API license is no longer required in order to develop applications against the Enterprise Vault APIs. 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. which specifies the mode of authentication to be used when the calling application contacts Enterprise Vault. E775452 Availability 45 . Table 2-24 Changes and corrections Ref Change details CAP031 ■ It is now possible to use the transaction Id instead of the saveset id when setting the Item::Id property. E804597 ■ IArchivingControl2 interface Enterprise Vault 7. and hence could not be moved. Enterprise Vault 7. 0 .46 API updates Enterprise Vault 7. These can be used by applications to access Enterprise Vault functionality. and not on the Enterprise Vault server. which expose task-specific interfaces. Overview of Enterprise Vault APIs Enterprise Vault SDK comprises a number of APIs. In general.NET objects. The various Enterprise Vault APIs are implemented as COM or . archiving items uses the IContentManagementAPI and IItem interfaces. . For example.Chapter 3 Enterprise Vault API overview This chapter includes the following topics: ■ About API overview ■ Overview of Enterprise Vault APIs ■ Prerequisite software and settings ■ Licensing ■ Deploying an application that uses the API ■ Installing the Enterprise Vault SDK ■ Programming notes About API overview This chapter introduces the Enterprise Vault SDK and the APIs it comprises. applications which use the APIs should be run from a client computer. ■ Get properties of vault stores and archives. . ■ Look up an existing retention category. ■ Enumerate collections of vault stores. (Legal Hold) ■ Remove any holds placed on items. Examples of possible applications are also given to provide guidance: Table 3-1 Enterprise Vault APIs API Description Content Management API ■ Create archives. ■ Add custom index metadata to an item as it is stored. (Legal Hold) ■ Archives and vault stores cannot be deleted using the Content Management API. retrieve. ■ Update an existing retention category. archives or items. Place holds on a group of items to prevent items from being deleted manually or by Enterprise Vault storage expiry. ■ Store. 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. copy. ■ Enumerate retention categories. ■ List the items in an archive. Table 3-1 lists the available APIs. ■ Get item properties. Retention API ■ Create new retention categories. move and delete archived items. ■ Set locks on a retention category.48 Enterprise Vault API overview Overview of Enterprise Vault APIs To help you choose the appropriate APIs for your application. If you are using the Content Management API. to create archives. then MSXML 6. which is assigned using the Enterprise Vault Administration Console.0 or later is required on the computer where you install the Enterprise Vault API runtime. Domino Filtering The Filtering APIs provide the ability to: API File System Filtering API Select certain items for processing (and possibly archiving). or a suitable Enterprise Vault administration role. subject text. If the calling application is acting on behalf of clients. the caller has to have sufficient permissions to access the target archive. Permissions In general. or a suitable Enterprise Vault administration role. This can be either Vault Service account permissions. Enterprise Vault administration roles are described in the Enterprise Vault Administrator's Guide. Similarly. based on attributes (for example. and has assumed the responsibility of checking client permissions prior to proxying calls to the API.Enterprise Vault API overview Prerequisite software and settings Table 3-1 API Enterprise Vault APIs (continued) Description Exchange Filtering External filters enable preprocessing of items in order to decide on API the actions to take. ■ Delete selected items without archiving them. the caller must have either Vault Service account permissions. Prerequisite software and settings Details of prerequisites for Enterprise Vault are described in the Installing and Configuring manual. ■ Store selected items in specific archives. ■ Add custom index metadata to selected items before they are archived. whether to archive the item and which archive settings to apply. sender). for example. ■ ■ Set a particular retention category on selected items. Vault Service account permissions are described in the Installing and Configuring manual. 49 . then the caller must have adequate administration permissions. However. ■ Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault 8. This license also covers management of content archived by Enterprise Vault. these developers would be granted a Not for Resale (NFR) license to develop to these APIs by membership of Symantec Technology Enabled Program (STEP).0 or later) for ingesting content into Enterprise Vault. In most circumstances. This license also covers management of content archived by Enterprise Vault. 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 and Enterprise Vault 2007) for management of content archived by Enterprise Vault. customer deployments of third-party applications which make use of the Enterprise Vault APIs will require the following license. 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.0 or later) for management of content archived by Enterprise Vault. Customer deployments of third-party applications and customer-developed applications that make use of the Enterprise Vault APIs will require one of the following licenses. ■ Symantec Generic Content Management Connector license (Enterprise Vault 7. Production licensing The STEP licensing contract does not grant production use of the Enterprise Vault APIs.50 Enterprise Vault API overview Licensing Licensing No additional Enterprise Vault license is required in order to develop applications against the Enterprise Vault APIs.0 and Enterprise Vault 2007) for ingesting content into Enterprise Vault.0) ■ Symantec Generic Ingest Agent license (Enterprise Vault 2007) This section describes the licensing requirements for the Enterprise Vault APIs. ■ Symantec Generic Ingest Agent license (Enterprise Vault 7. in addition to any third party licensing requirements: ■ Symantec Enterprise Vault Custom Archiving Agent license (Enterprise Vault 8. in addition to any third-party licensing requirements: . NET language bindings for .0 or later) for ingesting content into Enterprise Vault.0 and Enterprise Vault 2007) for management of content archived by Enterprise Vault. This license also covers management of content archived by Enterprise Vault.0 features. Enterprise Vault API runtime MSI The Enterprise Vault API runtime libraries are provided in the Windows installer kit Symantec Enterprise Vault API Runtime. if the application uses Enterprise Vault 8. The Enterprise Vault API runtime libraries are automatically installed with the Enterprise Vault server. Search and Retention APIs.0 or later. 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.NET managed code.Enterprise Vault API overview Deploying an application that uses the API ■ Symantec Enterprise Vault Custom Archiving Agent license (Enterprise Vault 8.msi on the Symantec Enterprise Vault release media. but it is not recommended that the application runs on the Enterprise Vault server. ■ Symantec Generic Content Management Connector license (Enterprise Vault 7. 51 . Note: The Enterprise Vault API runtime kit is not redistributable.0 or later) for management of content archived by Enterprise Vault. The runtime should be obtained from the customer's Enterprise Vault release media and installed on the server that will host the application. then the API runtime must be Enterprise Vault 8. ■ Symantec Generic Ingest Agent license (Enterprise Vault 7. This license also covers management of content archived by Enterprise Vault. 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. ■ Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault 8.0 and Enterprise Vault 2007) for ingesting content into Enterprise Vault. The runtime installer registers the COM objects for Content Management. and provides interoperability libraries for . For example. follow the instructions given in Checking version and installation path details prior to Enterprise Vault 8.0. To detect if Enterprise Vault server is installed. or the Enterprise Vault SDK. you can query the following registry settings directly: ■ HKEY_LOCAL_MACHINE \Software \KVS . and find out the installation location.52 Enterprise Vault API overview Deploying an application that uses the API If you are using Enterprise Vault 8. 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 To detect if Enterprise Vault API runtime libraries.0. 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. you can use the MsiGetProductInfo method and the relevant product code to find out the installation location (INSTALLPROPERTY_INSTALLLOCATION) of the runtime or SDK. are installed locally. Checking version and installation path details prior to Enterprise Vault 8.0 or later. 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. 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. and find out the installation location. 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. or directly using the Microsoft . The Interop assemblies can be generated indirectly using Visual Studio as part of the application build. a <bindingRedirect> element if the application is built against a different PIA version to the one deployed by the Enterprise Vault runtime. then Enterprise Vault server is installed.exe). When the application is deployed.dll Using Visual Studio the required API COM libraries. for example EVContentManagementAPI. See “Updating binding redirections in configuration files” on page 54. the application generates. The assembly redirections must include a <codebase> element that defines the location of the PIA and. ■ Alternatively.dll. ■ This requires an application configuration file with <dependentAssembly> entries for each of the Enterprise Vault API components used by the application.NET Framework Type Library Importer tool (tlbimp.NET application. should be added to the application's References. optionally. builds against. the application must ensure that suitable versions of the Interop assemblies for Enterprise Vault API components have been installed.Enterprise Vault API overview Deploying an application that uses the API \Enterprise Vault \Install \VaultServices If the value of this setting is "Installed". and deploys a set of Interop assemblies for those Enterprise Vault API components that are used by the application. 53 .NET applications When deploying a . For example: tlbimp /nologo EVContentManagementAPI. ■ HKEY_LOCAL_MACHINE \Software \KVS \Enterprise Vault \Install \InstallPath Deploying . it must be configured to use the PIAs provided by the Enterprise Vault API runtime. NET application that uses the Enterprise Vault API Runtime files.0. 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.0.Interop.dll"/> </dependentAssembly> </assemblyBinding> </runtime> 2 Apply the updates to the configuration file for each . which installs the following: ■ Enterprise Vault API runtime libraries ■ API samples ■ This manual in PDF and CHM format .IndexClient" culture="neutral" publicKeyToken="26c5e2ccf2b9267c"/> <bindingRedirect oldVersion="7. To update the application configuration file: 1 Open the client application's configuration file.Interop.5.54 Enterprise Vault API overview Installing the Enterprise Vault SDK Updating binding redirections in configuration files This section provides instructions on how to update the . locate the Enterprise Vault <assemblyIdentity> nodes.0" href= "FILE:///C:\Program Files\Enterprise Vault\ KVS.msi.IndexClient.0"/> <codeBase version="8.0.2534" newVersion="8.NET application configuration files to use a newer version of the Enterprise Vault API runtime.4.v1"> <dependentAssembly> <assemblyIdentity name="KVS. Symantec Enterprise Vault Software Development Kit. Installing the Enterprise Vault SDK The Enterprise Vault SDK is distributed as a Windows installer kit.EnterpriseVault.0.EnterpriseVault. A ReadMe file in the folder provides instructions on how to install and use the application. ■ Example filter 1 (SampleFilter. SDK examples The following examples are included in the SDK: ■ An example application for the Content Management API is installed in the folder. See “Checking version and installation path details prior to Enterprise Vault 8. retrieving items. InstallFolder\samples\ECM API Sample. InstallFolder\samples\FSA Filter Sample. A ReadMe file in the folder provides instructions on how to install and use the filters. follow the instructions given elsewhere. 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. 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. For example.0 or later.0” on page 52. avi.Enterprise Vault API overview Installing the Enterprise Vault SDK Checking the SDK version and installation path If you are using Enterprise Vault 8. 55 . depending on a variety of file properties. and viewing properties on items and archives. This application provides a UI that enables you to test out API functions such as creating an archive. one action is to delete files with any of the extensions.cs) configures different actions for the File System Archiving task.0. or mpeg. ■ Two example filters that use the File System Filtering API are installed in the folder. storing an item in an archive. mp3. interfaces and types. per thread. Programming notes ■ As the API interfaces are derived from IDispatch. raw_interfaces_only Using Enterprise Vault APIs in .56 Enterprise Vault API overview Programming notes ■ Example filter 2 (CustomProp. ■ When running scripts on a 64-bit operating system. See “Deploying . C:\Windows\SysWOW64\cmd. error wrapper functions and the EVContentManagementAPILib namespace: #import "EVContentManagementAPI.NET managed languages When using .NET applications” on page 53. such as a Content Management API object. error wrapper functions and the EVContentManagementAPILib namespace: #import "EVContentManagementAPI.NET definitions for the API COM type library. ASP web pages (using Visual Basic Script).NET languages (such as Visual Basic . ■ For best performance in a multi-threaded application. You can reference the SDK Primary Interop Assemblies (PIAs). and other languages that support COM. ■ The APIs can be used from C++. the COM API library or Interop assemblies generated via tlbimp.NET and C#). the associated DLL includes the type library for all of the classes. For example. Using the Enterprise Vault APIs in C++ For each API. they can be used by scripting languages. .dll" using namespace EVContentManagementAPILib. use the 32-bit version of command prompt. use a separate instance of an API object.dll" no_namespace. depending upon the deployment model selected. To exclude use of smart pointers. enumerations and interfaces of the API.NET managed languages to build an application using an API.cs) configures the File System Archiving task actions for Microsoft Office 2007 files that have custom properties added. . to use smart pointers. Interop assemblies provide the .exe. 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. When referencing an Interop assembly the API types are defined in the namespace of the COM type library name.dll When referencing a PIA the API types are defined in the namespace KVS. IArchive3 and IArchiveMetaData2. code samples are included for C++ and C#.0.EnterpriseVault.Enterprise Vault API overview Programming notes The Primary Interop Assemblies (PIAs). As Visual Basic . The Content Management API IDispatchQueryInterface method enables Visual Basic Script applications to perform a QueryInterface.EnterpriseVault. COM API libraries or Interop assemblies should be added to the project's references to provide definitions of the COM classes. interfaces and types. Other programming aspects. attention has been paid to the API specifics only. which were introduced at Enterprise Vault 8.Interop. Code samples In the code samples given in this manual. are not directly accessible by Visual Basic Script applications. For example the namespace for the Content Management API is EVContentManagementAPILib.EVContentManagementAPI. Using Enterprise Vault APIs in Visual Basic Script The Content Management API interfaces. to reference the Content Management API via its PIA. In general.NET is very similar to C#. separate examples are not included in most cases. For example.Interop. add : KVS. specifying the required interface's Interface Identifier (IID) string. such as error handling. 57 . have been omitted for clarity. 58 Enterprise Vault API overview Programming notes . Chapter Content Management API This chapter includes the following topics: ■ About the Content Management API ■ General guidelines for using the API ■ Enumerations ■ ContentManagementAPI object ■ IContentManagementAPI :: Archive ■ IContentManagementAPI :: Item ■ IContentManagementAPI :: Holds ■ IContentManagementAPI :: Hold ■ IContentManagementAPI :: DirectoryDNSAlias ■ IContentManagementAPI :: AuthenticationMode ■ IContentManagementAPI2 :: VaultStores ■ IContentManagementAPI2 :: VaultStore ■ IContentManagementAPI2 :: Archives ■ IContentManagementAPI3 :: Items ■ IContentManagementAPI3 :: IDispatchQueryInterface ■ IContentManagementAPI4 :: LastError ■ VaultStores object ■ IVaultStores :: Computer 4 . 60 Content Management API ■ VaultStore object ■ IVaultStore :: Id ■ IVaultStore :: Name ■ IVaultStore :: Description ■ IVaultStore :: Status ■ IVaultStore :: ArchiveCount ■ IVaultStore :: DirectoryDNSAlias ■ IVaultStore :: Get ■ Archives object ■ IArchives :: Computer ■ IArchives :: VaultStoreId ■ IArchives :: ArchiveName ■ IArchives :: Permissions ■ IArchives :: ArchiveTypes ■ Archive object ■ IArchive :: VaultStoreId ■ IArchive :: Id ■ IArchive :: Name ■ IArchive :: Description ■ IArchive :: ExpireItems ■ IArchive :: ConvertedContent ■ IArchive :: IndexUrgency ■ IArchive :: IndexLevel ■ IArchive :: Size ■ IArchive :: SecurityDescriptor ■ IArchive :: ComplianceDevice ■ IArchive :: ItemCount . Content Management API ■ IArchive :: Create ■ IArchive :: Get ■ IArchive2 :: Type ■ IArchive2 :: Status ■ IArchive2 :: HasFolders ■ IArchive2 :: Full ■ IArchive2 :: DirectoryDNSAlias ■ IArchive3 :: SecurityDescriptor ■ IArchive3 :: SecurityDescriptorString ■ IArchive3 :: Type ■ Items object ■ IItems :: ArchiveId ■ IItems :: StartSequenceNum ■ IItems :: OrderBy ■ Item object ■ IItem :: ArchiveId ■ IItem :: Id ■ IItem :: Content ■ IItem :: ArchiveMetaData ■ IItem :: BrowserViewURL ■ IItem :: DefaultMSGFormat ■ IItem :: Holds ■ IItem :: NativeItemURL ■ IItem :: DeletionLevel ■ IItem :: CopyOptions ■ IItem :: Insert ■ IItem :: Get 61 . 62 Content Management API ■ IItem :: Delete ■ IItem :: CanBeDeleted ■ IItem :: CopyTo ■ IItem :: MoveTo ■ IItem2 :: DeletionReason ■ IItem3 :: Undelete ■ Content object ■ IContent :: Title ■ IContent :: OriginalLocation ■ IContent :: FileExtension ■ IContent :: MIMEFormat ■ IContent :: CreatedDate ■ IContent :: ModifiedDate ■ IContent :: Data ■ IContent :: OriginalSize ■ IContent :: Author ■ ArchiveMetaData object ■ IArchiveMetaData :: RetentionCategory ■ IArchiveMetaData :: ComplianceDevice ■ IArchiveMetaData :: OverrideOnHoldRetCat ■ IArchiveMetaData :: ArchivedDate ■ IArchiveMetaData :: ComplianceData ■ IArchiveMetaData :: SavesetSize ■ IArchiveMetaData :: RetentionExpires ■ IArchiveMetaData :: IndexData ■ IArchiveMetaData :: IsItemSecured ■ IIArchiveMetaData :: CustomIdentifier . Content Management API ■ IIArchiveMetaData :: CustomQualifier ■ IIArchiveMetaData :: CustomProperties ■ IArchiveMetaData :: Update ■ IArchiveMetaData2 :: CurrentLocation ■ IArchiveMetaData2 :: CurrentFolderId ■ IArchiveMetaData2 :: SequenceNum ■ IArchiveMetaData2 :: ArchivedDate ■ SimpleIndexMetadata object ■ ISimpleIndexMetadata :: _NewEnum ■ ISimpleIndexMetadata :: DateTimesUTC ■ ISimpleIndexMetadata :: Count ■ ISimpleIndexMetadata :: Add ■ ISimpleIndexMetadata :: Clear ■ ISimpleIndexMetadata :: ToXML ■ ISimpleIndexMetadata :: FromXML ■ ISimpleIndexMetadata :: ToLocalTime ■ ISimpleIndexMetadata :: ToUTCTime ■ SimpleIndexProperty object ■ ISimpleIndexProperty :: Set ■ ISimpleIndexProperty :: Name ■ ISimpleIndexProperty :: Value ■ ISimpleIndexProperty :: Searchable ■ ISimpleIndexProperty :: Retrievable ■ ISimpleIndexProperty :: System ■ ComplianceData object ■ IComplianceData :: Units ■ IComplianceData :: Value 63 . 64 Content Management API ■ IComplianceData :: SetBy ■ Holds object ■ IHolds :: _NewEnum ■ IHolds :: Item ■ IHolds :: Count ■ IHolds :: GroupId ■ IHolds :: ConsumerGUID ■ IHolds :: Metadata ■ IHolds :: Add ■ IHolds :: PlaceHolds ■ IHolds :: ReleaseHolds ■ IHolds2 :: ReleaseHolds2 ■ Hold object ■ IHold :: ArchiveId ■ IHold :: ItemId ■ IHold :: Id ■ IHold :: Status ■ IHold :: Metadata ■ IHold :: ConsumerGUID ■ IHold :: GroupId ■ ICollectionBase : IDispatch ■ ICollectionBase :: Count ■ ICollectionBase :: _NewEnum ■ ICollectionBase :: Item ■ ICollectionBase :: Maximum ■ ICollectionBase :: More ■ ICollectionBase :: Get . Content Management API About the Content Management API ■ ICollectionBase :: Clear ■ ICollectionBase :: Reset ■ ExtendedErrorInfo object ■ IExtendedErrorInfo :: Error ■ IExtendedErrorInfo :: Description ■ IExtendedErrorInfo :: InnerError ■ IExtendedErrorInfo :: InnerErrorDescription ■ IExtendedErrorInfo :: Source ■ DiagnosticsAPI object ■ IDiagnosticsAPI : Name ■ IDiagnosticsAPI : IsTraceEnabled ■ IDiagnosticsAPI : LogEvent ■ IDiagnosticsAPI : Trace 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 65 . . 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. When working with Lotus Notes databases.66 Content Management API About the Content Management API ■ IItem2 ■ IItem3 ■ IContent ■ IArchiveMetaData ■ IArchiveMetaData2 ■ ISimpleIndexMetadata ■ IComplianceData ■ IHolds ■ IHold ■ IExtendedErrorInfo ■ IDiagnosticsAPI The methods and properties exposed by all these interfaces are described in detail in this chapter. Architecture of Content Management API Figure 4-1 illustrates the organization of the Content Management API objects. You can use the Content Management API to store notes in the archive or retrieve notes from the archive. Content Management API About the Content Management API Figure 4-1 Hierarchy of Content Management API objects <<object>> ContentManagementAPI <<object>> <<object>> <<object>> <<object>> VaultStores Archives Items Holds <<object>> VaultStore <<object>> Archive <<object>> Item <<object>> ArchiveMetaData <<object>> ComplianceData <<object>> Hold <<object>> Content <<object>> SimpleIndexMetadata <<object>> ExtendedErrorInfo <<object>> DiagnosticsAPI <<object>> SimpleIndexProperty All the objects shown are exposed by the Content Management API: 67 . ■ The Items object enables applications to enumerate the items in an archive in batches. VaultStore. The Items object exposes a standard COM collection interface that manages a collection of Item objects. The Enterprise Vault index sequence number of an archived item is used to determine the first item in a batch.The VaultStores object exposes a standard COM collection interface that manages a collection of VaultStore objects.68 Content Management API About the Content Management API ■ The ContentManagementAPI object provides a means of accessing the other objects. The Archives object exposes a standard COM collection interface that manages a collection of Archive objects. or by decreasing the index sequence number (most recently archived item first). ISimpleIndexMetadata interface enables the calling application to add custom index metadata to an object as it is archived. These objects enable the examination of vault stores and archives in Enterprise Vault. ■ The Archive object enables the creation of archives in an Enterprise Vault vault store. type and permissions. ■ The Item object provides applications with a way to store and manage items in Enterprise Vault archives. The following interfaces are exposed by IArchiveMetaData: IComplianceData interface describes the compliance metadata set on an item in an archive. ■ The VaultStores object enables applications to enumerate the vault stores configured in an Enterprise Vault site. ■ The Hold object describes a hold that is placed on an item. An Items collection can be enumerated by increasing the index sequence number (oldest archived item first). ■ IArchiveMetaData interface provides calling applications with a set of properties that describe how the item is archived. The properties enable the selection of archives using a combination of archive name. 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. ■ The Archives object enables applications to enumerate archives in a vault store. . 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. such as VaultStores. This can then be searched for using the Search API. It exposes a standard COM collection interface that manages a collection of IHold objects. Archives and Item. ■ The DiagnosticsAPI object enables calling applications to use the Enterprise Vault tracing utility. and frequent creation and release would result in poor performance of the client. Once an object instance has been used (that is. ■ Populate its properties (ArchiveId. as the ContentManagementAPI object caches information from Enterprise Vault.NET managed code). Content etc. it can only be used for querying properties. Get. Most of the object instances obtained from the ContentManagementAPI object are designed to be used only once. Insert or Create have been called). for example. by calling CoCreateInstance (C++).). If the API application archives large numbers of items. the following steps are required when storing an item in an archive: ■ Obtain an instance of an empty Item object by calling IContentManagementAPI::Item. not for setting them. ArchiveMetaData. For example. This prevents reuse of stale data. Use of objects It is best practice for the calling application to keep the ContentManagementAPI object alive as long as possible. See “ContentManagementAPI object” on page 87. Before any of these methods (Get. ■ Call the Insert method. 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. and write to the Enterprise Vault event log. and is considered less important than normal Enterprise Vault Exchange Server archiving. the existing object instance should be released and a new one obtained. Insert or Create) can be called again. 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. You can then use the properties and methods on the interface to obtain instances of other objects.Content Management API General guidelines for using the API ■ The ExtendedErrorInfo object provides calling applications with additional information on internal errors encountered when using Content Management API interfaces. then the API application should run with a lower thread priority than THREAD_PRIORITY_NORMAL. 69 . Dtrace. or by using the new operator (. ■ Enumerate through the collection.70 Content Management API General guidelines for using the API ■ Retrieve the item's Id from the object property. This is a success return value. You can select archives using the following criteria: ■ By vault store. . For example. optionally filtered by archive type. optionally filtered by archive type. When coding in C++ the S_FALSE return value should be handled using the Windows SUCCEEDED or FAILED macros. ■ By name or partial name. return the default property value and an S_FALSE return value when reading the property before it has been written. ■ Populate the selection criteria properties. IArchives and IItems interfaces inherit the properties and methods of a generic collection enumeration interface. calling applications need to be able to find target vault stores and archives. and retrieve information about these items from the Enterprise Vault Storage Service. or searching for archived items using the Search API. If you attempt to do so an error will be reported.Id. The IItems interface enables the application to enumerate the items in an archive. ■ By caller's access permissions. You cannot just repopulate the properties and call Insert again. These interfaces enable calling applications to enumerate and select vault stores and archives. and retrieve information about these from the Enterprise Vault Directory. When storing or retrieving items using the Content Management API. archives and items Archives are held in vault stores. Enumerating vault stores. ■ Release the Item object instance. The IVaultStores. for example Item. all FSA archives that the caller has permission to search. This functionality is provided by the IVaultStores and the IArchives interfaces. With vault stores. and items are held in archives. How to use this interface follows the general model for enumerating objects: ■ Obtain an empty collection instance from the ContentManagementAPI. ■ By archive type. you can only select all vault stores in an Enterprise Vault Site. optionally filtered by archive type. ICollectionBase. A number of object properties. ■ Invoke the Get method to populate the collection. When coding in C# it is not possible to differentiate between the S_OK and S_FALSE return values. This form of identifier should be used for long term storage of the archived item ID. optionally in ascending or descending order. 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. a 128 bit number. When such items are copied or moved. Property validation The syntax of a property is validated when the property is set. The Transaction ID would typically only be used to identify an item processed during filtering. ■ By start item Index Sequence Number (ISN). or in GUID Registry format (that is.Content Management API General guidelines for using the API You select items using the following criteria: ■ By archive.0 have a 31 hexadecimal character Transaction ID value. for example when invoking the Get method. for example. Saveset IDs and Transaction IDs An archived item can be identified by either a Saveset ID or a Transaction ID. The Transaction ID is a short form identifier. 71 . Items stored using a version of Enterprise Vault prior to Enterprise Vault 8. 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. Format of a Transaction ID value A Transaction ID can be specified as a 32 hexadecimal character string. It is a GUID. and is an element within the Saveset ID. {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx}). the Transaction ID value is extended to 32 hexadecimal characters by appending a zero (‘0’) hexadecimal character. For performance reasons. but validation of the value is typically delayed until the property is used. the Id property will then hold the Saveset ID of the item. the latter format is used when the IItem::Id property is populated by the Items collection object. The Saveset ID is the long form identifier and fully identifies the archived item. "FC0A3C5E5A7D45E6AB3BC5382EB640D". that uniquely identifies the archived item within a vault store. the search is performed on the index associated with the archive. The appendix includes information about how Enterprise Vault processes sender and recipient details when archiving and retrieving messages. Adding custom index metadata Applications can add custom index metadata to an item as it is archived. not on the archive itself. Figure 4-2 illustrates how custom index metadata is added to an item using the Content Management API.72 Content Management API General guidelines for using the API How Enterprise Vault processes message items How Enterprise Vault processes message items is described later in an appendix to this guide. When the item is indexed. . Details are given for the different types of messages supported. See “About storing and retrieving message items” on page 627. and copying or moving archived messages. The Search API can then be used to search archives for items with the custom information. this custom metadata will be included in the index for the item. When an archive is searched. Note that custom index metadata properties cannot be added to attachments. ■ In the Domino Filtering API and File System Filtering API. use the method IArchivingControl4 :: AddIndexedPropertyEx. Custom filtering is available for Exchange Mailbox Archiving Tasks. or one of the Filtering APIs: ■ In the Content Management API. See “IArchivingControl interface” on page 402. See “IArchivingControl interface for Exchange filtering” on page 360. ■ In the Exchange Filtering API. 73 . Exchange Public Folder Tasks and Exchange Journaling Tasks.Content Management API General guidelines for using the API Figure 4-2 Adding metadata to the index of an item Third party application IContentManagementAPI ContentManagementAPI Enterprise Vault Storage Vault store service Insert() + metadata Item ID ArchiveID Content ArchiveMetaData IndexData Enterprise Vault Indexing Index service ISimpleIndexMetadata SimpleIndexPropert SimpleIndexPropert y SimpleIndexPropert y ySimpleIndexPropert ySimpleIndexPropery Enterprise Vault server You can add custom index metadata to an item using the Content Management API. See “IArchiveMetaData :: IndexData” on page 236. See “SimpleIndexMetadata object” on page 256. use the Add method in the IndexMetadata class. use the methods on the ISimpleIndexMetadata interface. If you want to add a custom index date property that is retrievable only. specify the property set and name of the custom index property in the form propertySet.asp?advanced About number and date custom index properties When adding dateTime index properties where the time element is significant. When an index property is stored in the index as a string. the date range values that can be returned in search results are limited to the UTC date range 1st January 1970 to 1st January 2038. Auditing for various categories of item operations from all Enterprise Vault agents can be enabled or disabled. In particular. and the string value is returned in search results without alteration. no attempt is made to parse the value as a date. Audit logging can be enabled for specific audit categories using the Enterprise Vault Administration Console.74 Content Management API General guidelines for using the API To check that the metadata has been indexed. Items that are indexed with dateTime properties later than 1 Jan 2038 are also returned in the index search results. In the Name field. If the custom index property is defined as searchable. For example: http://evserver/enterprisevault/search. you can use the Other attribute fields in Enterprise Vault browser search to specify the name and value of the custom index property. Audit logging From Enterprise Vault 8. Items that are indexed with dateTime properties earlier than 1 Jan 1970 are returned in the index search results. specify the value of a dateTime index property using the ISO 8601 format. Note that adding a large number of custom index properties will increase the index size. and can reduce search performance. but the retrieved date values defaults to 1 Jan 2038. perform an archive search for the custom information. then you can specify a string index property instead of a dateTime index property.propertyName. This avoids time zone ambiguities. When searching using date search criteria.0. 2012-07-27T19:30:00+01:00. but the retrieved date values defaults to 1 Jan 1970. . To see the Other attribute fields in browser search. audit logging includes Content Management API item operations. For example. add ?advanced to the browser search URL. Table 4-1 lists the operations that can be logged and the associated Enterprise Vault audit category. searchable numbers and dateTime index properties impact search performance more than string properties. Content Management API Enumerations Table 4-1 Operations logged and the associated audit category API operation Enterprise Vault Audit Category Insert Archive CopyTo MoveTo Archive Delete1 Delete Delete Get View 1. 75 . Items can be deleted completely (hard delete). DiagnosticsAPI can be used from any external application. The default value is DELETION_LEVEL_SOFT_DELETE. 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). 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. one for the item insertion and another for the item deletion from the original location. Enumerations This section describes the enumerations used by the Content Management API. including external filters.MoveTo will support two audit entries. or moved to the Enterprise Vault "dumpster" area (soft delete). DELETION_LEVEL_HARD_DELETE = 1 }. See “IItem :: DeletionLevel” on page 185. the administrator can enable the recovery of deleted items and specify how long soft-deleted items are to be kept. EVENT_TYPE_WARNING = 2. ITEMS_ORDERBY_DESC = 1 }. See “IItems :: OrderBy” on page 170. This enumeration value is set using the Item DeletionLevel property. EVENT_TYPE_INFORMATION = 3. items are enumerated using ascending index sequence number order. EVENT_TYPE_SUCCESS_AUDIT = 4. EVENT_TYPE_FAILURE_AUDIT = 5 }. in the Site Properties pages.76 Content Management API Enumerations In the Enterprise Vault Administration Console. The default value is ITEMS_ORDERBY_ASC. EV_API_TRACE_LEVEL enumeration Trace level enumeration indicates the trace level: . When an application creates a diagnostic message in the Enterprise Vault event log using the DiagnosticsAPI LogEvent method. EV_API_EVENT_TYPE enumeration Event type enumeration indicates the type of event: enum EV_API_EVENT_TYPE { EVENT_TYPE_ERROR = 1. See “IDiagnosticsAPI : LogEvent” on page 325. EV_API_ITEMS_ORDERBY enumeration Items collection order defines whether to increase or decrease the index sequence number when enumerating a collection of items. this value indicates the type of message to create. enum EV_API_ITEMS_ORDERBY { ITEMS_ORDERBY_ASC = 0. See “IDiagnosticsAPI : IsTraceEnabled” on page 325.Content Management API Enumerations enum EV_API_TRACE_LEVEL { TRACE_LEVEL_HIGH = 1. See “IArchive3 :: Type” on page 162. the DiagnosticsAPI Trace method uses this enumeration to set the trace level to be associated with the message. TRACE_LEVEL_LOW = 3 }. 0x00000002. 0x00000001. TRACE_LEVEL_MEDIUM = 2. 0x00000020. The method DiagnosticsAPI IsTraceEnabled tests if the specified level of tracing is enabled in the application for the Enterprise Vault tracing utility (Dtrace). 0x00000004. = = = = = = = = = 0x00000000. EV_STG_API_ARCHIVE_TYPE enumeration Archive type enumeration indicates the type of archive: enum EV_STG_API_ARCHIVE_TYPE { ARCHIVE_TYPE_NOT_SET ARCHIVE_TYPE_SHARED ARCHIVE_TYPE_EXCHANGE_MAILBOX ARCHIVE_TYPE_EXCHANGE_JOURNAL ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER ARCHIVE_TYPE_FILE_SYSTEM ARCHIVE_TYPE_SHAREPOINT ARCHIVE_TYPE_DOMINO_JOURNAL ARCHIVE_TYPE_DOMINO_MAILBOX }. 77 . See “IArchives :: ArchiveTypes” on page 127. 0x00000008. EV_STG_API_AUTHENTICATE_USING enumeration Storage authentication enumeration indicates the authentication mode to use when authenticating to Enterprise Vault. IArchives::ArchiveTypes and IArchive3::Type. 0x00000040. 0x00000010. When sending a trace message to Dtace. select archives based on the type of archive specified by this enumeration. 0x00000080 The properties. See “IDiagnosticsAPI : Trace” on page 326. EV_STG_API_CAN_DELETE enumeration Can delete enumeration indicates whether or not the item can be deleted. See “IContentManagementAPI :: AuthenticationMode” on page 99. DELETE_ACCESS_DENIED = 1. AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default value. DELETE_ITEM_COMPLIANCE The compliance device on which the item is stored does not permit deletion See “IItem :: CanBeDeleted” on page 200. AUTHENTICATE_USING_AUTHSERVER = 1 AUTHENTICATE_USING_MOST_APPROPRIATE_MODE = 2 }. DELETE_ITEM_COMPLIANCE = 8 }. The Item CanBeDeleted method returns the current value for an item.78 Content Management API Enumerations enum EV_STG_API_AUTHENTICATE_USING { AUTHENTICATE_USING_DCOM_SECURITY = 0. enum EV_STG_API_CAN_DELETE { DELETE_ALLOWED = 0. Authentication using the Enterprise Vault authentication server can only be used by applications installed on a configured Enterprise Vault server. DELETE_RETCAT_ONHOLD = 2. or the archive may be in a read-only state. and should only be used on advice from Symantec Support. This value means that DCOM will be used. . 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_ONHOLD = 4. 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. It indicates where the compliance retention period is set: enum EV_STG_API_CP_SETBY { SETBY_NOTSET = 0. SETBY_RETCAT = 2 }. the Enterprise Vault Storage Service converts the file to HTML. ComplianceData SetBy.Content Management API Enumerations EV_STG_API_CONVERTED_CONTENT enumeration When a file is archived. or generated on demand: enum EV_STG_API_CONVERTED_CONTENT { CONVERTED_CONTENT_STORED = 0. See “IArchiveMetaData :: ComplianceData” on page 233. The property. See “IArchive :: ConvertedContent” on page 138. SETBY_RETCAT (Default) The compliance retention period is set by the associated Enterprise Vault retention category. SETBY_SELF The compliance retention period is set by the caller using the ComplianceData object. is used to set or retrieve the enumeration value. The property. CONVERTED_CONTENT_ON_DEMAND = 1 }. Archive ConvertedContent. EV_STG_API_CP_SETBY enumeration Compliance set by enumeration is for use with compliance devices only. if possible. Store converted content enumeration indicates whether converted content is stored with the item. The HTML version is also presented to users when the item is previewed or viewed using the Enterprise Vault Web Access application. 79 . SETBY_SELF = 1. The HTML version is used by the Indexing Service to index the item. uses this enumeration value to define where the compliance retention period is set: SETBY_NOTSET A compliance retention period is not set. CP_UNITS_MONTHS = 2. . CP_UNITS_DEFAULT = 4. The enumeration values have the following meanings: DELETION_REASON_NONE (Default) Indicates that the item has not yet been deleted. 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. enum EV_STG_API_DELETION_REASON { DELETION_REASON_NONE = 0.80 Content Management API Enumerations See “IComplianceData :: SetBy” on page 284. DELETION_REASON_SYSTEM = 3 DELETION_REASON_UNKNOWN = 2147483647 } If an item no longer exists in the archive. See “IComplianceData :: Units” on page 282. the Item DeletionReason property uses the EV_STG_API_DELETION_REASON enumeration. CP_UNITS_YEARS = 3. DELETION_REASON_USER = 1. DELETION_REASON_USER Indicates that the item was deleted by a user. DELETION_REASON_EXPIRY = 2. CP_UNITS_NONE = 5 }. CP_UNITS_WEEKS = 1. CP_UNITS_NONE is actually the default value. the Item DeletionReason property can be used to find out why the item was deleted. not CP_UNITS_DEFAULT. EV_STG_API_DELETION_REASON enumeration Deletion reason enumeration indicates why an item has been deleted from the archive. or set the required value for a new archive before Archive Create is called. See “IArchive :: ExpireItems” on page 136. INDEX_LEVEL_MEDIUM = 1. or if Enterprise Vault could not complete the archiving process because the vault store could not be backed up.Content Management API Enumerations DELETION_REASON_EXPIRY Indicates that the item was deleted by Enterprise Vault expiry deletion. The Enterprise Vault Indexing service manages the indexes of archived data to enable users to search for archived items. INDEX_LEVEL_DEFAULT = 3 }. DELETION_REASON_SYSTEM Indicates that the item was deleted by the Enterprise Vault system. When users search the archives to 81 . 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. DELETION_REASON_UNKNOWN Indicates that the reason why the item was deleted cannot be identified. See “IItem2 :: DeletionReason” on page 208. EV_STG_API_EXPIRE_ITEMS enumeration Expire items enumeration indicates whether expired items should be deleted automatically from the archive: enum EV_STG_API_EXPIRE_ITEMS { DONT_EXPIRE_ITEMS = 0. EXPIRE_ITEMS = 1 }. INDEX_LEVEL_FULL = 2. This value may be returned. when the archive has been deleted. for example. The property Archive ExpireItems can be used to return the enumeration value for an existing archive. See “IArchive :: IndexUrgency” on page 140. See “About indexing options” on page 442. INDEX_ITEMS_DEFER_INDEFINITELY = 1 }. The more information that is indexed about an item.0 server. Deferring indexing may be useful if you want to store a very large number of items quickly. the more information that is indexed about an item.82 Content Management API Enumerations which they have access. FULL indexing is required for phrase searches of the content property (IndexPropCONT). If INDEX_LEVEL_MEDIUM is requested on an Enterprise Vault 10. The Archive IndexUrgency property is used to access index urgency information. Thereafter. then INDEX_LEVEL_FULL is implemented. If INDEX_ITEMS_DEFER_INDEFINITELY is set. the more disk space is required for the index. the next time the Indexing Service runs. See “IArchive :: IndexLevel” on page 142. However. IArchive::IndexLevel. the quicker it is to find the item. Note: INDEX_LEVEL_MEDIUM is only available on servers running Enterprise Vault 9 or earlier. 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. it will process the indexing backlog. the items will not be indexed until the value has been reset to IMMEDIATELY. 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. . the index volume files are searched. The property. is used to determine the level of detail stored in the archive's index. ■ 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. EV_STG_API_ITEM_DETAIL enumeration Item detail enumeration indicates the data to populate for an Item. DETAIL_LEVEL_CUSTOM_INDEX_METADATA = 32. 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. DETAIL_LEVEL_ARCHIVE_METADATA = 4.Get request: enum EV_STG_API_ITEM_DETAIL { DETAIL_LEVEL_ITEM_PROPERTIES = 1. unless explicitly provided as part of the CopyTo or MoveTo method call: SimpleIndexMetadata ArchivedDate RetentionCategory CurrentLocation CurrentFolder CustomIdentifier CustomQualifier CustomProperties ■ ITEM_COPYOPTIONS_MERGE_INDEXMETADATA If this is set. DETAIL_LEVEL_ITEM_CONTENT = 2. DETAIL_LEVEL_HOLD_DATA = 16. DETAIL_LEVEL_SYSTEM_INDEXDATA = 64.Content Management API Enumerations enum EV_STG_API_ITEM_COPYOPTIONS { ITEM_COPYOPTIONS_UNSPECIFIED = 0x00000000. DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA = 128 83 . See “IItem :: CopyOptions” on page 187. DETAIL_LEVEL_COMPLIANCE_DATA = 8. ITEM_COPYOPTIONS_ARCHIVEMETADATA = 0x00000002. ITEM_COPYOPTIONS_MERGE_INDEXMETADATA = 0x00000004 } . The default value is ITEM_COPYOPTIONS_ARCHIVEMETADATA. CustomQualifier IArchiveMetadata.CurrentFolderId IArchiveMetadata.CanBeDeleted IArchiveMetadata.RetentionCategory IArchiveMetadata.Author IContent.Data DETAIL_LEVEL__ARCHIVE_METADATA IArchiveMetadata. DETAIL_LEVEL_ITEM_CONTENT IContent.IsItemSecured See “Content object” on page 212.ComplianceDevice IArchiveMetadata. Table 4-2 Properties populated for EV_STG_API_ITEM_DETAIL enumeration values Enumeration value Properties populated DETAIL_LEVEL_ITEM_PROPERTIES IContent.ModifiedDate IContent.CreatedDate IContent. See “ArchiveMetaData object” on page 225.OriginalLocation IContent.RetentionExpires .OriginalSize IItem.Title IContent.CustomIdentifier IArchiveMetadata. See “Item object” on page 172. The following table lists the properties that are populated for the different item detail levels.FileExtension IContent.84 Content Management API Enumerations DETAIL_LEVEL_SENDER_RECIPIENT_INDEXDATA = 256 }.SequenceNum DETAIL_LEVEL__COMPLIANCE_DATA IArchiveMetadata.SavesetSize IArchiveMetadata.MIMEFormat IContent.CustomProperties IArchiveMetadata.ArchivedDate IArchiveMetadata. PERMISSIONS_WRITE = 0x00000002. DETAIL_LEVEL__MESSAGE_ENVELOPE_INDEXDATA IArchiveMetadata.IndexData — "sere" system property only.IndexData — "menv" system property only. See “System properties” on page 596. See “System properties” on page 596. PERMISSIONS_DELETE = 0x00000004. 85 . See “Adding custom index metadata” on page 72.IndexData — system properties only. (System properties are not included).Holds See “Holds object” on page 285. DETAIL_LEVEL__SENDER_RECIPIENT_INDEXDATA IArchiveMetadata. PERMISSIONS_READ = 0x00000001. PERMISSIONS_FOLDER_DELETE = 0x00000020. PERMISSIONS_SEARCH = 0x00000080. excluding the "menv" and "sere" properties. PERMISSIONS_FOLDER_WRITE = 0x00000010.IndexData — custom index properties only. See “System properties” on page 596.Content Management API Enumerations Table 4-2 Properties populated for EV_STG_API_ITEM_DETAIL enumeration values (continued) Enumeration value Properties populated DETAIL_LEVEL__HOLD_DATA IItem. DETAIL_LEVEL__SYSTEM_INDEXDATA IArchiveMetadata. DETAIL_LEVEL__CUSTOM_INDEX_METADATA IArchiveMetadata. See “System properties” on page 596. PERMISSIONS_FOLDER_READ = 0x00000008. EV_STG_API_PERMISSIONS_TYPE enumeration Archive permissions enumeration indicates archive permissions: enum EV_STG_API_PERMISSIONS_TYPE { PERMISSIONS_UNSPECIFIED = 0x00000000. See “IItem :: Get” on page 194. . }. 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.86 Content Management API Enumerations PERMISSIONS_READ_WRITE = PERMISSIONS_READ|PERMISSIONS_WRITE. PERMISSIONS_WRITE_DELETE = PERMISSIONS_WRITE |PERMISSIONS_DELETE. PERMISSIONS_FOLDER_WRITE_DELETE = PERMISSIONS_FOLDER__WRITE |PERMISSIONS_FOLDER_DELETE. PERMISSIONS_READ_WRITE_DELETE = PERMISSIONS_READ |PERMISSIONS_WRITE |PERMISSIONS_DELETE. The Archive SecurityDescriptor property represents the manually set permissions on an archive. PERMISSIONS_FOLDER_READ_WRITE= PERMISSIONS_FOLDER_READ |PERMISSIONS_FOLDER_WRITE. PERMISSIONS_FOLDER_READ_WRITE_DELETE = PERMISSIONSFOLDER__READ |PERMISSIONS_FOLDER_WRITE |PERMISSIONS_FOLDER_DELETE. The Archives Permissions property uses this enumeration to select archives based on the archive access permissions of the caller. which are displayed on the Permissions tab of the archive properties dialog in the Enterprise Vault Administration Console. PERMISSIONS_READ_DELETE = PERMISSIONS_READ |PERMISSIONS_DELETE. EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security descriptor permissions for an archive. See “IArchives :: Permissions” on page 126. STS_UNAVAILABLE = 1. PERMISSIONS_FOLDER_READ_DELETE = PERMISSIONS_FOLDER_READ |PERMISSIONS_FOLDER_DELETE. See “IArchive3 :: SecurityDescriptor” on page 157. STS_TEMPORARILY_UNAVAILABLE = 2 STS_INBACKUPMODE = 3 }. vault stores and items. and enables you to set and retrieve the Directory DNS Alias and Authentication mode. The IContentManagementAPI4 interface provides calling applications with extended error information if an error is encountered when using the Content Management API methods. and a method to enable applications written in Visual Basic script to access the IContentManagementAPI3 interface. Syntax interface interface interface interface IContentManagementAPI : IDispatch IContentManagementAPI2 : IContentManagementAPI IContentManagementAPI3 : IContentManagementAPI2 IContentManagementAPI4 : IContentManagementAPI3 87 . items and holds. See “IVaultStore :: Status” on page 115. See “IArchive2 :: Status” on page 154. and whether it can be accessed. The IContentManagementAPI2 interface provides additional properties for accessing Enterprise Vault Directory information about vault stores and archives. ContentManagementAPI object This object provides top-level access (via the appropriate interfaces) to archives. This object implements the following interfaces: ■ IContentManagementAPI ■ IContentManagementAPI2 ■ IContentManagementAPI3 ■ IContentManagementAPI4 (default) The IContentManagementAPI interface defines methods and properties enabling access to archives. The IContentManagementAPI3 interface provides a property for enumerating items stored in an archive.Content Management API ContentManagementAPI object The VaultStore Status and Archive Status properties use this enumeration to indicate the status of the vault store or archive. This interface inherits the methods of the IDispatch interface. AuthenticationMode Read/Write Gets or sets the authentication mode. VaultStore Read only Returns an empty instance of a VaultStore object. Table 4-5 IContentManagementAPI3 property Property Read/Write Description Items Read only Returns an empty instance of an Items object. DirectoryDNSAlias Read/Write Identifies an Enterprise Vault server running an Enterprise Vault Directory Service. Item Read only Returns an empty instance of an Item object.88 Content Management API ContentManagementAPI object Member summary Table 4-3 IContentManagementAPI properties Property Read/Write Description Archive Read only Returns an empty instance of an Archive object. Holds Read only Returns an empty instance of a Holds object. Table 4-4 IContentManagementAPI2 properties Property Read/Write Description VaultStores Read only Returns an empty instance of a VaultStores object. Hold Read only Returns an empty instance of a Hold object. . Archives Read only Returns an empty instance of an Archives object. enumerate and delete items. CLSID E4BE20A4-9EF1-4B05-9117-AF43EAB4B295 89 .0 or later is required on the computer where you install the Enterprise Vault API runtime. Requirements ■ MSXML 6. which provides extended error information if an error is encountered when using a Content Management API method. and IHolds. move. fetch. This enables applications written in Visual Basic script to access the IContentManagementAPI3 interface. IArchives. See “General guidelines for using the API” on page 69. depending on the Interface Indentifier string (IID) passed to it. IItem. IHold. Remarks This interface returns pointers to instances of other interfaces. as required. The properties of these need to be set so that they can then be used to create.Content Management API ContentManagementAPI object Table 4-6 IContentManagementAPI3 method Method Read/Write Description IDispatchQueryInterface Read/Write Returns an interface pointer for either the IArchiveMetaData3 or IArchive3 interface. The interface also enables you to get and set the Directory DNS Alias and the authentication mode for accessing Enterprise Vault. such as IVaultStores. Table 4-7 IContentManagementAPI4 method Method Read Description LastError Read Returns an interface pointer to an ExtendedErrorInfo object. public: void SomeClass() { CLSID clsid.0 SP2 or later.dll . NUKK. &clsid).Interop Version information ■ The property.ContentManagmentAPI".90 Content Management API ContentManagementAPI object Prog ID EnterpriseVault. ■ The IContentManagementAPI3 interface requires Enterprise Vault 8.EVContentManagementAPI.NET Primary Interop Assembly (PIA) KVS.0 or later. __uuidof . CLSIDFromProgID(L"EnterpriseVault.Interop. ■ The IContentManagementAPI2 interface requires Enterprise Vault 2007 or later.EnterpriseVault. Examples [C++] #import "c:\program files\Enterprise Vault\ EVContentManagementAPI.NET PIA namespace KVS.EnterpriseVault. ■ The IContentManagementAPI4 interface requires Enterprise Vault 8.dll .dll" no_namespace.ContentManagementAPI Type Library EVContentManagementAPILib DLL EVContentManagementAPI. raw_interfaces_only class SomeClass { IContentManagementAPI4* m_pCmAPI = NULL.0 or later. CLSCTX_ALL. IContentManagementAPI::AuthenticationMode requires Enterprise Vault 7. CoCreateInstance(clsid. Interop. Syntax HRESULT Archive([out. reinterpret_cast<LPVOID*> (&m_pCmAPI)). to the location of the IArchive pointer to the newly created archive object.EnterpriseVault. or modifying various properties. public class SomeClass { IContentManagementAPI4 cmAPI = new ContentManagementClass(). This property is read only. when successful. Remarks After the Create method or Get method has been called. This parameter is set to NULL if an error occurs. //rest of class } IContentManagementAPI :: Archive This property returns an empty instance of an Archive object that can then be used to perform various tasks.retval] IArchive** pVal A pointer. this interface pointer must be released and a new one obtained before calling either of these methods again.Content Management API IContentManagementAPI :: Archive (IContentManagementAPI). //do something else } [C#] using KVS. such as creating an archive.retval] IArchive** pVal) Parameters [out. 91 . archive = null.Archive. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. m_pCmAPI (C++) or cmAPI (C#) has already been obtained.Get(). archive. //Do something pArchive->Release().92 Content Management API IContentManagementAPI :: Archive Return value S_OK Success. .FinalReleaseComObject(archive). pArchive = NULL. [C++] IArchive* pArchive = NULL: m_pCmAPI->get_Archive(&pArchive). Examples In the following examples it is assumed a reference to IContentManagmentAPI. pArchive->put_Id(bstrID).Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". CComBSTR bstrVaultStoreId(L"16D002240AEDFAC45A44E7FBE88FDC7721 210000EVSite"). //do something System. CComBSTR bstrID(L"1C9EFA88998592944ADB634ACC0D7410D1110000EVSite").Runtime. pArchive->put_VaultStoreId(bstrVaultStoreId).VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".InteropServices. pArchive->Get(). archive. [C#] IArchive archive = cmAPI. archive. Return value S_OK Success. retval] IItem** pVal A pointer. Delete or Get method has been called. copying or moving items. retval] IItem** pVal) Parameters [out. such as creating an item and adding it to an archive. fetching data. This property is read only. to the location of the IItem pointer to the newly created item object. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. this interface pointer must be released and a new one obtained before calling any of these methods again.Content Management API IContentManagementAPI :: Item 93 IContentManagementAPI :: Item This property returns an instance of an Item object that can then be used to perform various tasks. deleting items from an archive. pItem->put_Id(bstrID). //note transaction id used CComBSTR bstrArchId(L"1C9EFA88998592944ADB634ACC0D7410 D1110000EVSite"). CComBSTR bstrID(L"68bd9b6a-6355-4468-b647-0ec33ade6340"). Examples [C++] IItem* pItem = NULL: m_pCmAPI->get_Item(&pItem). when successful. Remarks After the Insert. . getting item properties. Syntax HRESULT Item([out. This parameter is set to NULL if an error occurs. Id = "68bd9b6a-6355-4468-b647-0ec33ade6340". itm. //get item properties itm. . itm. //Do something with the properties pItem->Release(). It exposes a standard COM interface (IEnumVariant). This property is read only. IHolds is one of the interfaces that provides Legal Hold functionality. which manages a collection of IHold objects.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".InteropServices.Item. ■ See “SimpleIndexMetadata object” on page 256. [C#] IItem itm = cmAPI. //get item properties pItem->Get(DETAIL_LEVEL_ITEM_PROPERTIES). ■ See “ArchiveMetaData object” on page 225.Runtime.FinalReleaseComObject(item). 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. item = null.94 Content Management API IContentManagementAPI :: Holds pItem->put_ArchiveId(bstrArchId).Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES). pItem = NULL. System. See also ■ See “Content object” on page 212.Marshal. Remarks The IHold objects used to populate the Holds collection must be obtained using the Hold property of IContentManagementAPI. [C#] IHolds holds = cmAPI. retval] IHolds** pVal) Parameters [out. retval] IHolds** pVal A pointer. holds = null. Return value S_OK Success. See also ■ See “Holds object” on page 285. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.InteropServices.FinalReleaseComObject(holds). pHolds = NULL.Content Management API IContentManagementAPI :: Holds Syntax HRESULT Holds([out. //Do something pHolds->Release().Holds. to the location of the IHolds pointer to the newly created item object. when successful. 95 .Runtime. //do something System. Examples [C++] IHolds* pHolds = NULL: m_pCmAPI->get_Holds(&pHolds). This parameter is set to NULL if an error occurs. m_pCmAPI->get_Hold(&pHold). Return value S_OK Success. to the location of the IHold pointer to the newly created item object. retval] IHold** pVal). Remarks The IHold interface is the mechanism by which hold(s) are placed on an item archived in Enterprise Vault. when successful. Parameters [out. IHold* pHold = NULL. When a hold has been placed on an item.96 Content Management API IContentManagementAPI :: Hold ■ See “Hold object” on page 300. . This parameter is set to NULL if an error occurs. IHold is one of the interfaces that provides Legal Hold functionality This property is read only. The Holds collection is exposed via the IHolds interface. retval] IHold** pVal A pointer. the item cannot be deleted from the archive until the hold is released. IContentManagementAPI :: Hold This property returns an empty instance of a Hold object that can then be used to place an item on hold. Syntax HRESULT Hold([out. Examples [C++] IHolds* pHolds = NULL: m_pCmAPI->get_Holds(&pHolds). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. The interface allows various properties to be set before the Hold is added to the Holds collection in Enterprise Vault. //add some properties holds. pHold = NULL.InteropServices. retval] BSTR* pVal). [C#] IHolds holds = cmAPI.Hold. IContentManagementAPI :: DirectoryDNSAlias This property is used to identify a computer running an Enterprise Vault Directory Service. pHold->Release().Add(hold).InteropServices.Runtime. System. pHolds = NULL. HRESULT DirectoryDNSAlias([in] BSTR newVal). ■ See “Hold object” on page 300. holds = null.Holds.FinalReleaseComObject(holds). See also ■ See “Holds object” on page 285.FinalReleaseComObject(hold). 97 . pHolds->Release(). This property is read/write. in order to retrieve information from the Enterprise Vault Directory. Syntax HRESULT DirectoryDNSAlias([out. System. hold = null.Content Management API IContentManagementAPI :: DirectoryDNSAlias //Set properties pHolds->Add(pHold). IHold hold = cmAPI.Runtime. in the properties dialog for an archive. Similarly. ■ Id of the Enterprise Vault Site. will contain the current value. the ID of a vault store can be found in the Administration Console. ■ IP address of a computer hosting an Enterprise Vault Directory Service. //Do something . Remarks The ID of an Enterprise Vault site can be found in the following registry entry on an Enterprise Vault server: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \SiteID The ID of an archive can be found in the Enterprise Vault Administration Console. Examples [C++] CComBSTR bstrDNS(L"EVSERVER1"). Return value S_OK Success. m_pCmAPI->get_DirectoryDNSAlias(&bstrDNS). in the properties dialog for a vault store. ■ ■ Id of any archive in the Site.98 Content Management API IContentManagementAPI :: DirectoryDNSAlias Parameters [out. ■ Id of any vault store in the Site. retval] BSTR* pVal Pointer to a BSTR that. on return. [in] BSTR newVal The new value can be any one of the following: DNS alias of a computer hosting an Enterprise Vault Directory Service. DirectoryDNSAlias = dns. [in] cmAPI. retval] EV_STG_API_AUTHENTICATE_USING* pVal) HRESULT AuthenticationMode([in] EV_STG_API_AUTHENTICATE_USING newVal) Parameters [out. 99 . The property is read/write. IContentManagementAPI :: AuthenticationMode This property is used to get or set the mode to be used when authenticating to Enterprise Vault. retval]EV_STG_API_AUTHENTICATE_USING* pVal Pointer to an EV_STG_API_ AUTHENTICATE _USING object which will return the current authentication mode. Remarks The EV_STG_API_AUTHENTICATE_USING enumerator defines the authentication mode to use.DirectoryDNSAlias. Syntax HRESULT AuthenticationMode([out. This can be either DCOM or Enterprise Vault authentication server.Content Management API IContentManagementAPI :: AuthenticationMode [C#] [out] string dns = cmAPI. [in]EV_STG_API_AUTHENTICATE_USING newVal New value for the authentication mode. From Enterprise Vault 7.0. From Enterprise Vault 8.0. which enables applications to enumerate details of the vault stores configured in Enterprise Vault. Authentication using the Enterprise Vault authentication server can only be used by applications installed on a configured Enterprise Vault server. DCOM authentication is used by default. Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default enumeration value.100 Content Management API IContentManagementAPI2 :: VaultStores See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 77. retval] IUnknown** pVal).AUTHENTICATE_USING_DCOM_SECURITY. IContentManagementAPI2 :: VaultStores This property returns an empty instance of the VaultStores object. authentication was performed using DCOM when the API application was not installed on an Enterprise Vault server. [C#] cmAPI. Syntax HRESULT VaultStores([out. . otherwise Enterprise Vault authentication server was used. Examples [C++] m_pCmAPI->put_AuthenticationMode(AUTHENTICATE_USING_DCOM_SECURITY).0 SP2.AuthenticationMode = EV_STG_API_AUTHENTICATE_USING. and should only be used on advice from Symantec Support. In releases prior to Enterprise Vault 7. This value means that DCOM will be used. which can be used to read the details of a vault store. 101 . retval] IUnknown** pVal Reference to an empty VaultStores object. Return value S_OK Success. vaultStores. [C#] IVaultStores vaultStores = cmAPI.Content Management API IContentManagementAPI2 :: VaultStore Parameters [out. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL Examples [C++] IVaultStores pVaultStores = NULL.Computer = "EVSERVER1".Get(). This property is read only. See also ■ See “VaultStores object” on page 107. a pointer to an IUnknown* that can be QI'd (cast) for an IVaultStores interface pointer. vaultStores. pVaultStores->put_Computer(bstrComputer). CComBSTR bstrComputer(L"EVSERVER1").VaultStores. Remarks When successful. m_pCmAPI->get_VaultStores(&pVaultStores). IContentManagementAPI2 :: VaultStore This property returns an empty instance of the VaultStore object. pVaultStores->Get(). 102 Content Management API IContentManagementAPI2 :: VaultStore Syntax HRESULT VaultStore([out. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL Examples [C++] CComPtr<IVaultStore> spVaultStore. Parameters [out. spUnk->QueryInterface(&spVaultStore). spVaultstore->Get(). m_pCmAPI->get_VaultStore(&pUnk). . CComPtr<IUnknown> spUnk. Return value S_OK Success.Get(). retval] IUnknown** pVal). vaultStore. Remarks To populate the Vault Store object. See also ■ See “VaultStore object” on page 110. retval] IUnknown** pVal Reference to an empty VaultStore object.VaultStore. CComBSTR bstrID(L"16D002240AEDFAC45A44E7FBE88FDC772121 0000EVSite"). [C#] IVaultStore vaultStore = cmAPI.ID = "16D002240AEDFAC45A44E7FBE88FDC7721210000 EVSite". vaultStore. spVaultStore->put_Id(bstrID). set the Id property to that of the vault store then call Get. Return value S_OK Success. Syntax HRESULT Archives([out. CComPtr<IUnknown> spUnk. Applications can then enumerate the items in the archive. See also ■ See “Archives object” on page 119. Parameters [out. 103 .Content Management API IContentManagementAPI2 :: Archives IContentManagementAPI2 :: Archives This property returns an instance of the Archives collection object. spUnk->QueryInterface(&spArchives). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL Example [C++] CComPtr<IArchives> spArchives. which enables applications to enumerate archives configured in the current vault store. m_pCmAPI->get_Archives(&spUnk). IContentManagementAPI3 :: Items This property returns an empty instance of the Items object. retval] IUnknown** pVal). CComBSTR bstrVaultStore(L"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"). spArchives->put_ArchiveTypes(ARCHIVE_TYPE_EXCHANGE_MAILBOX). retval] IUnknown** pVal An instance of an Archives object. spArchives->put_VaultStore(bstrVaultStore). which is populated by calling IItems::Get. // Get an Items object for enumeration spCMapi->get_Items(&spUnk). Return value S_OK Success. retval] IUnknown** pVal). Parameters [out. spCMAPI. retval] IUnknown** pVal Reference to an empty Items object. CComQIPtr<IItems> spItems(spUnk). Remarks An IItems interface pointer can be obtained by calling QueryInterface on the returned IUnknown* pointer. See also ■ See “Items object” on page 164. CComPtr<IUnknown> spUnk. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL Example [C++] // Get empty items collection for populating CComPtr<IContentManagementAPI3> spCMAPI. IContentManagementAPI3 :: IDispatchQueryInterface This method enables calling applications written in Visual Basic Script to access the properties of the following interfaces: .ContentManagement API")).CreateInstance(CComBSTR(L"EnterpriseVault.104 Content Management API IContentManagementAPI3 :: IDispatchQueryInterface Syntax HRESULT Items([out. [in] BSTR interfaceId Interface Identifier (IID) string associated with the interface being queried. or interfaceId is empty. When running scripts on a 64-bit operating system. Remarks The pointer for returning the queried interface object returns NULL. or the interface is not available on the object being queried. 105 . Return value S_OK Success CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either of pUnkObj or ppUnkRetVal are NULL. [in] BSTR interfaceId. retval] IDispatch** ppUnkRetVal Pointer for returning the queried interface object. and an error is reported. [out. C:\Windows\SysWOW64\cmd. IItem2 was introduced at Enterprise Vault 8.exe. use the 32-bit version of command prompt. is not a valid interface ID (IID).0. if the interface is not supported.Content Management API IContentManagementAPI3 :: IDispatchQueryInterface ■ IArchive3 ■ IArchiveMetaData2 ■ IItem2 IArchive3 and IArchiveMetaData2 were introduced at Enterprise Vault 8. [out. Parameters [in] IDispatch* pUnkObj IDispatch interface pointer associated with the object being queried. Syntax HRESULT IDispatchQueryInterface ([in] IDispatch* pUnkObj. retval] IDispatch** ppUnkRetVal).0 SP3. dim cmAPI. item.ArchiveMetaData. in order to access the IArchiveMetaData2::SequenceNum property. ■ See “ArchiveMetaData object” on page 225. Syntax HRESULT LastError([out. "{5C6882BD-24BE-4C32-87EF-C3701D949BAA}") if (IAMD2 is nothing) then MsgBox "ArchiveMetaData2 API Object create failed!" end if SeqNo = IAMD2.IDispatchQueryInterface(item.106 Content Management API IContentManagementAPI4 :: LastError 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.SequenceNum See also ■ See “Archive object” on page 128. Remarks The ExtendedErrorInfo object provides error details for the last call to a Content Management API method.ContentManagementAPI") set item = ContentManagementAPI.Item set IAMD2 = cmAPI. Parameters [out. SeqNo.retval] IUnknown** pVal A reference to an ExtendedErrorInfo object. . IContentManagementAPI4 :: LastError This method provides calling applications with extended error information if an error is encountered when using the Content Management API methods. IAMD2 set cmAPI = CreateObject("EnterpriseVault.retval] IUnknown** pVal). VaultStores object This object implements the following interface: ■ IVaultStores The IVaultStores interface inherits the properties and methods of the ICollectionBase interface. See “Programming notes” on page 56. 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. Return value S_OK Success See also ■ See “ExtendedErrorInfo object” on page 316. See Table 4-9 on page 108. See Table 4-10 on page 108. The IVaultStores interface enables applications to enumerate the vault stores configured in an Enterprise Vault Site. as this could cause error information from a call on another thread to be returned. 107 . Details of the properties and methods of the ICollectionBase interface are provided in later sections of this guide.Content Management API VaultStores object It is important to follow recommended best practice. and avoid sharing IContentManagementAPI interface objects across threads. Maximum Read/Write Maximum number of vault stores in the collection. and automatically populate the properties of each VaultStore object . [C#] IContentManagementAPI3 cmAPI = (IContentManagementAPI3) . Clear Clear the current collection.108 Content Management API VaultStores object Table 4-9 ICollectionBase properties Property Read/Write Description Count Read only Number of vault stores in the collection. Version information ■ This interface is available from Enterprise Vault 2007. Reset Reset the object back to the initial state. _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. Remarks Use the ICollectionBase :: Get method of this interface to obtain a collection of VaultStore objects. See “VaultStore object” on page 110. More Read only Whether or not there were more vault stores than Maximum. Example This example code lists all vault stores based on a Computer DNS name. Table 4-10 ICollectionBase methods Method Description Get Populate the collection. VaultStores. HRESULT Computer([out. such as site or vault store.com". The property is read/write.Get().Name). // Populate collection from EV1 vaultStores. retval] BSTR* pVal A pointer to a string that will hold the returned value.Content Management API IVaultStores :: Computer new ContentManagementAPI(). Parameters [in] BSTR pVal The DNS name of an Enterprise Vault server. vaultStore. for example: ■ DNS name ■ IP address ■ The Id of an Enterprise Vault entity.Computer = "EV1. IVaultStores vaultStores = (IVaultStores) CMAPI. [out. vaultStores. Syntax HRESULT Computer([in] BSTR pVal). or the Id of an Enterprise Vault entity.Acme.Id. retval] BSTR* pVal). } IVaultStores :: Computer This property identifies an Enterprise Vault server running a Directory Service. Remarks This property can be set with any identifier that Enterprise Vault can use to identify an Enterprise Vault server running a Directory Service. // Process each Vault Store foreach(IVaultStore vaultStore in vaultStores) { ProcessIt(vaultStore. for example: ■ Enterprise Vault Site Id ■ Vault store Id ■ Archive Id 109 . Id.Name).Computer = "EV1.VaultStores. Return value S_OK Success.com". CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL Example [C#] IContentManagementAPI3 cmAPI = (IContentManagementAPI3) new ContentManagementAPI().Acme. // Populate collection from EV1 vaultStores. its value defaults to the current value of the DirectoryDNSAlias property of the parent IContentManagementAPI instance. Similarly. vaultStore. If the Computer property is left empty. } VaultStore object This object implements the following interface: . in the properties dialog for an archive. IVaultStores vaultStores = (IVaultStores) CMAPI. vaultStores. the Id of a vault store can be found in the Administration Console. // Process each Vault Store foreach(IVaultStore vaultStore in vaultStores) { ProcessIt(vaultStore.110 Content Management API VaultStore object The Id of an Enterprise Vault Site can be found in the following registry entry on an Enterprise Vault server: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \SiteID The Id of an archive can be found in the Enterprise Vault Administration Console. in the properties dialog for a vault store.Get(). you can call the Get method to populate the VaultStore properties. Alternatively. Version information ■ This interface is available from Enterprise Vault 2007. if you select a specific vault store using the Id property. IVaultStore methods Method Description Get Get the details of the selected vault store. Description Read only Vault store description. 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. DirectoryDNSAlias Read only Table 4-12 Identifies an Enterprise Vault server running an Enterprise Vault Directory Service. Status Read only Status of vault store. ArchiveCount Read only Number of archives in the vault store. See “VaultStores object” on page 107. then the IVaultStore properties are populated automatically for each vault store returned. 111 .Content Management API VaultStore object ■ IVaultStore The IVaultStore interface enables external applications to get details of a vault store. Remarks If you use the ICollectionBase interface to enumerate vault stores. Return value S_OK Success. . string description = vaultsStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". vaultStore. string dnsAlias = vaultStore.ArchiveCount. vaultStore. HRESULT Id([in] BSTR newVal). Syntax HRESULT Id([out. long count = vaultStore.Status. //now get vault store properties string name = vaultStore.Get(). [out. retval] BSTR* pVal).VaultStore. IVaultStore :: Id This property contains the Id of the target vault store. in the properties dialog for a vault store. retval] BSTR* pVal String that will contain the Id of the vault store.Name.112 Content Management API IVaultStore :: Id Example [C#] IVaultStore vaultStore = cmAPI. The property is read/write. Parameters [in] BSTR pVal Id of the required vault store.Description. EV_STG_API_STATUS evStatus = vaultStore.DirectoryDNSAlias. Remarks The Id of a vault store can be found in the Administration Console. Status. //now get vault store properties string name = vaultStore.Get().Content Management API IVaultStore :: Name CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. Parameter [out. The property is read only. vaultStore.Description.DirectoryDNSAlias. retval] BSTR* pVal). 113 . Syntax HRESULT Name([out.VaultStore. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. string description = vaultsStore. retval] BSTR* pVal Name of the vault store. pVal is not a valid Vault Store identity.ArchiveCount. vaultStore. or the object is already populated.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". EV_STG_API_STATUS evStatus = vaultStore.Name. Return value S_OK Success. string dnsAlias = vaultStore. Example [C#] IVaultStore vaultStore = cmAPI. IVaultStore :: Name This property contains the name of the selected vault store. long count = vaultStore. The property is read only. string description = vaultsStore. //now get vault store properties .VaultStore.114 Content Management API IVaultStore :: Description Example [C#] IVaultStore vaultStore = cmAPI. Return value S_OK Success.VaultStore. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. //now get vault store properties string name = vaultStore.Status. vaultStore.Name.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". retval] BSTR* pVal Vault store description. Parameter [out. vaultStore. vaultStore.Description. string dnsAlias = vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". IVaultStore :: Description This property contains the vault store description. long count = vaultStore. Example [C#] IVaultStore vaultStore = cmAPI. vaultStore.Get().DirectoryDNSAlias. Syntax HRESULT Description([out. EV_STG_API_STATUS evStatus = vaultStore.ArchiveCount. retval] BSTR* pVal).Get(). Return value S_OK Success. The property is read only.VaultStore. retval] EV_STG_API_STATUS* pVal EV_STG_API_STATUS enumerated value. Syntax HRESULT Status([out. string dnsAlias = vaultStore.Content Management API IVaultStore :: Status string name = vaultStore. IVaultStore :: Status This property contains the status of the vault store. vaultStore. Example [C#] IVaultStore vaultStore = cmAPI. Parameter [out. See “EV_STG_API_STATUS enumeration” on page 86. EV_STG_API_STATUS evStatus = vaultStore. Remarks EV_STG_API_STATUS is an enumerated type. 115 .Name. string description = vaultsStore. long count = vaultStore. //now get vault store properties string name = vaultStore. vaultStore.Name. string description = vaultsStore. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. retval] EV_STG_API_STATUS* pVal).Description.Status.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".Count.Get().DirectoryDNSAlias.Description. retval] long* pVal). .DirectoryDNSAlias. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.116 Content Management API IVaultStore :: ArchiveCount string dnsAlias = vaultStore.Status. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. long count = vaultStore.ArchiveCount. Return value S_OK Success. Parameter [out. For this reason. Remarks This property is populated using an additional call to the Enterprise Vault server. EV_STG_API_STATUS evStatus = vaultStore. The request should be retried later. retval] long* pVal Number of archives currently in the vault store. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory service is not running. Syntax HRESULT ArchiveCount([out. The property is read only. it is only populated when explicitly requested. IVaultStore :: ArchiveCount This property contains the number of archives in the vault store. string dnsAlias = vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". IVaultStore :: DirectoryDNSAlias This property contains the DNS Alias created for the Enterprise Vault Site.Content Management API IVaultStore :: DirectoryDNSAlias Example [C#] IVaultStore vaultStore = cmAPI. Parameter [out.VaultStore. Return value S_OK Success.Get(). 117 . Syntax HRESULT DirectoryDNSAlias([out.Description.ArchiveCount. The property is read only. vaultStore. Remarks When configuring Enterprise Vault. long count = vaultStore. EV_STG_API_STATUS evStatus = vaultStore. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. retval] BSTR* pVal DNS alias for the Enterprise Vault Site. //now get vault store properties string name = vaultStore. retval] BSTR* pVal).Name. vaultStore. 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. string description = vaultsStore.Status.DirectoryDNSAlias. then you can set the Id property of the IVaultStore interface and call Get to populate the IVaultStore properties. CONTENTMANAGEMENTAPI_E_NOT_FOUND The vault store does not exist. .Status. Remarks If you do not enumerate vault stores using the IVaultStores interface. Syntax HRESULT Get(void). vaultStore. //now get vault store properties string name = vaultStore.118 Content Management API IVaultStore :: Get Example [C#] IVaultStore vaultStore = cmAPI. vaultStore.VaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".Name. string dnsAlias = vaultStore. string description = vaultsStore. long count = vaultStore.Description.ArchiveCount.Get(). CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory service is not running. IVaultStore :: Get This method returns the properties for the selected vault store. EV_STG_API_STATUS evStatus = vaultStore.DirectoryDNSAlias. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Id property is empty. Return value S_OK Success. Archives object This object implements the following interface: ■ IArchives The IArchives interface inherits the properties and methods of the ICollectionBase interface. string dnsAlias = vaultStore.Name.DirectoryDNSAlias. type.VaultStore. //now get vault store properties string name = vaultStore.Content Management API Archives object CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". permissions or vault store. string description = vaultsStore. The request should be retried later. vaultStore.ArchiveCount. Syntax interface IArchives : ICollectionBase 119 . This interface enables applications to enumerate archives optionally filtered by archive name. Example [C#] IVaultStore vaultStore = cmAPI.Description. long count = vaultStore.Status. vaultStore.Get(). EV_STG_API_STATUS evStatus = vaultStore. . VaultStoreId Read/Write Id of the vault store containing the required archive or archives. Maximum Read/Write Maximum number of archives in the collection. See Table 4-15 on page 121.120 Content Management API Archives object Member summary Table 4-13 IArchives properties Property Read/Write Description Computer Read/Write An Enterprise Vault server running an Enterprise Vault Directory Service. More Read only Indicates whether there are more archives available than the maximum allowed in the collection. Item Read only Instance of the archive at the zero-based index into the collection. Permissions Read/Write Caller's access permissions on the required archive or archives. ArchiveName Read/Write Name. See Table 4-14 on page 120. or part of the name. of the required archive or archives. ArchiveTypes Read/Write Types of archives required. The properties and methods of the ICollectionBase interface are described in later sections. 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. based on the DNS Alias for an Enterprise Vault Site. Clear Clear the current collection. Example This example lists all Exchange Server mailbox archives that can be searched by the caller.Archives. [C#] IArchives archives = (IArchives)cmAPI. Reset Reset the object back to the initial state. 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. subject to the following rules: ■ ■ If you set Computer. 121 . Version information ■ This interface requires Enterprise Vault 2007 or later. 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. Remarks Use the ICollectionBase :: Get method of this interface to obtain a collection of Archive objects.Content Management API Archives object Table 4-15 ICollectionBase methods Method Description Get Populate the collection. the only other property that you can set is ArchiveType. No other combinations of properties are supported. IArchives :: Computer This property identifies an Enterprise Vault server running a Directory Service. for example: ■ DNS name ■ IP address ■ The Id of an Enterprise Vault entity in the Directory.122 Content Management API IArchives :: Computer See also ■ See “Enumerating vault stores. retval] BSTR* pVal A pointer to a string that will hold the returned value. HRESULT Computer([out. retval] BSTR* pVal). [out. Remarks This property can be set with any identifier that Enterprise Vault can use to identify an Enterprise Vault server running a Directory Service. such as site or vault store. archives and items” on page 70. Parameters [in] BSTR pVal The DNS name of an Enterprise Vault server. 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: . ■ See “Archive object” on page 128. or the Id of an Enterprise Vault entity. ■ See “ICollectionBase : IDispatch” on page 308. Syntax HRESULT Computer([in] BSTR pVal). The property is read/write. 123 . Similarly. archives. archives.Permissions = EV_STG_API_PERMISSIONS_TYPE. its value defaults to the current value of the DirectoryDNSAlias property of the parent IContentManagementAPI instance.PERMISSIONS_SEARCH.Archives. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.Content Management API IArchives :: VaultStoreId HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \SiteID The Id of an archive can be found in the Enterprise Vault Administration Console.Computer = "EV1. IArchives :: VaultStoreId This property contains the Id of the vault store that contains the required archive or archives. in the properties dialog for an archive. If the Computer property is left empty.com". Example This example gets all the archives that the user has permission to search. Return value S_OK Success. [C#] IArchives archives = (IArchives)cmAPI.Get(). The property is read/write. archives. the Id of a vault store can be found in the Administration Console. in the properties dialog for a vault store.acme. in the properties dialog for a vault store.VaulStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". retval] BSTR* pVal String that will contain the Id of the vault store. or by enumerating vault stores using the VaultStores object.Get().ArchiveTypes = EV_STG_API_ARCHIVE_TYPE.124 Content Management API IArchives :: ArchiveName Syntax HRESULT VaultStoreId([in] BSTR pVal). . archs. retval] BSTR* pVal). Return value S_OK Success. HRESULT VaultStoreId([out. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or pVal is not a valid vault store identity.ARCHIVE_TYPE_EXCHANGE_MAILBOX. [C#] IArchives archs = (IArchives)cmAPI. Example This example gets all Exchange Server mailbox archives in a particular vault store. archs.Archives. Parameters [in] BSTR pVal Id of the required vault store. The property is read/write. Remarks The Id of a vault store can be found in the Administration Console. archs. IArchives :: ArchiveName This property enables archives to be selected by name or partial name. [out. retval] BSTR* pVal). Parameters [in] BSTR pVal Name or partial name of required archive or archives. ■ [] matches any single character within the specified range or set (case insensitive). 125 . or f.Content Management API IArchives :: ArchiveName Syntax HRESULT ArchiveName([in] BSTR pVal).c.b.d. [^] to match any single character not in the specified range or set (case insensitive). or f. For example. HRESULT ArchiveName([out.b. \ escapes *. or [ to enable matching on those characters. retval] BSTR* pVal Pointer to a string that will contain the archive names.c. or f. 50\% is used to match with 50%. For example ■ ■ ■ [abdf] to match any of the set of characters a. Remarks Multiple archives can be selected by use of common wildcard syntax. ■ [a-f] to match any of the range of characters a. The returned collection is ordered by archive name.d. ■ % to match any single character.b. ■ [^a-f] to match any character not in the range of characters a. Return value S_OK Success. %.e.e. b. or f.d. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. The following wildcard features are supported: ■ * to match none. For example ■ [^abdf] to match any character not in the set of characters a.d. [out. one or any number of characters. See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 85. Syntax HRESULT Permissions([in] EV_STG_API_PERMISSIONS_TYPE pVal). retval] EV_STG_API_PERMISSIONS_TYPE* pVal). Parameters [in] EV_STG_API_PERMISSIONS_TYPE pVal New EV_STG_API _PERMISSIONS_TYPE value. [out. archs. The permissions checks are based on the current Windows identity of the caller. then the impersonation identity is used. archs. .ArchiveName = "*Smith". The property is read/write. [C#] IArchives archs = cmAPI. HRESULT Permissions([out.Get(). If the caller is currently impersonating. retval] EV_STG_API_PERMISSIONS_TYPE* pVal Caller's archive access permissions.126 Content Management API IArchives :: Permissions Example This example retrieves all archives with a name ending in ‘Smith’. archs.Computer = "SERVER1". IArchives :: Permissions This property enables selection of archives based on the archive access permissions of the caller. Currently there is no support for the Lotus Domino authentication model. Remarks EV_STG_API_PERMISSIONS_TYPE is an enumerated type that indicates the required archive permissions.Archives. Permissions = EV_STG_API_PERMISSIONS_TYPE. Remarks EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive. SharePoint archive.com". FSA archive. HRESULT ArchiveTypes([out. Exchange Server mailbox archive. For example. IArchives :: ArchiveTypes This property enables the selection of archives based on the type of archive. archives. See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 77. Example [C#] IArchives archives = (IArchives)cmAPI. Parameters [in] LONG pVal One or more values of EV_STG_API_ARCHIVE_TYPE.acme. 127 . Syntax HRESULT ArchiveTypes([in] LONG pVal)). and so on.PERMISSIONS_SEARCH. The property is read/write. [out. retval] LONG* pVal).Get(). archives. archives.Archives.Computer = "EV1.Content Management API IArchives :: ArchiveTypes Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. retval] LONG* pVal One or more values of EV_STG_API_ARCHIVE_TYPE. ARCHIVE_TYPE_EXCHANGE_MAILBOX. Example [C#] IArchives archives = (IArchives)cmAPI. Syntax interface IArchive : IDispatch interface IArchive2 : IArchive interface IArchive3 : IArchive2 . CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. archives.ArchiveTypes = (int)EV_STG_API_ARCHIVE_TYPE.Permissions = (int)EV_STG_API_PERMISSIONS_TYPE. archives. 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.PERMISSION_SEARCH.Archives.128 Content Management API Archive object Return value S_OK Success.Get(). 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. archives. specified as a variant byte array containing a SECURITY_DESCRIPTOR structure. Name Read/Write Name of the archive. ItemCount Read only Number of items in the archive. IndexLevel Read/Write Sets level of indexing. (This is not the original item size) SecurityDescriptor Write only Security permissions for the archive. ConvertedContent Read/Write Controls whether converted content is stored with item or generated on demand. 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.Content Management API Archive object Member summary Table 4-16 IArchive properties Property Read/Write Description VaultStoreId Read/Write Identifies the vault store in which the archive resides. ExpireItems Read/Write Enables automatic storage expiry for archive. ComplianceDevice Read only Indicates whether the archive resides on a device capable of setting compliance periods. IndexUrgency Read/Write Control whether items are indexed on archiving. Size Read only Size of the archive. 129 . Description Read/Write Provides description of the archive. Id Read/Write Archive ID of the archive. that is. whether it can be accessed. SecurityDescriptorString Read/Write The security permissions on the archive specified using Security Descriptor String Format as described in MSDN. 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.130 Content Management API Archive object Table 4-17 IArchive2 properties (continued) Property Read/Write Description HasFolders Read only Whether archive structure is flat or has folders. Get Retrieves details of the selected archive.0 or later. Table 4-19 IArchive methods Method Description Create Creates an archive. . Type Read/Write The type of the archive. the reference must be released and a new one obtained before calling either of these methods again. ■ IArchive3 interface requires Enterprise Vault 8. DirectoryDNSAlias Read only Directory DNS Alias of the hosting the archive. Full Read only Whether the archive is full. Version information ■ IArchive2 interface requires Enterprise Vault 2007 or later. Remarks After the Create method or Get method has been called on this interface. retval] BSTR* pVal) Parameters [in] BSTR newVal Id of the required vault store. arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". Example arch. Syntax HRESULT VaultStoreId([in] BSTR newVal) HRESULT VaultStoreId([out.Get(). arch. arch. The property is read/write.Get(). .Archive arch.Content Management API IArchive :: VaultStoreId 131 Example [C#] IArchive arch = cmAPI. IArchive :: VaultStoreId This property identifies the vault store in which the archive resides or will reside.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".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. [out. 132 Content Management API IArchive :: Id IArchive :: Id This property contains the Archive Id of the archive. If an attempt to change this value on an existing archive is made then an error will occur.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. HRESULT Id([in] BSTR newVal). . Remarks This value must be set prior to calling Get. pVal is not a valid archive identity. retval] BSTR* pVal). This property is read/write. The following is an example value of the Id property: "181E669473B52E64384C9A7D9EACA0E7E1110000evsite" Return value S_OK Success. or the object is already populated. This value is displayed in the properties of the archive in the Administration Console. Parameters [in] BSTR newVal The Archive Id of the archive. Syntax HRESULT Id([out. Examples arch. retval] BSTR* pVal Pointer to a BSTR that will contain the current value. Maximum length of string: 112 characters. [out. or [out] Assume an Archives object. and cannot be blank or an empty string. Syntax HRESULT Name([in] BSTR newVal) HRESULT Name([out. } IArchive :: Name This property is used to set the name for a new archive or retrieve the name of an existing archive.retval] BSTR* pVal) Parameters [in] BSTR newVal The name of the archive.Get().Id).Content Management API IArchive :: Name arch. foreach (IArchive archive in archives) { SearchArchive(archive. The value must contain printable characters only.retval] BSTR* pVal Pointer to a BSTR that will contain the name of an archive. [out. Remarks This property must be set before creating an archive. Maximum length: 256 characters. The property is read/write. has been populated. 133 . Any attempt to change the name of an existing archive will result in an error.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". ‘archives’. but is not required to get an archive. arch. string description = arch.Description.ComplianceDevice. arch.ConvertedContent.ExpireItems = EV_STG_API_EXPIRE_ITEMS. EV_STG_API_INDEX_URGENCY evIU = arch. string name = arch. arch. arch.IndexUrgency. bool complianceDevice = arch. EV_STG_API_EXPIRE_ITEMS evEI = arch.Name. newVal contains invalid characters. arch. EV_STG_API_INDEX_LEVEL evIL = arch.ItemCount.Get().Create(). arch. DONT_EXPIRE_ITEMS. INDEX_LEVEL_FULL. arch. INDEX_ITEMS_IMMEDIATELY. ulong size = (ulong) arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".IndexLevel. Example [in] arch.IndexLevel = EV_STG_API_INDEX_LEVEL.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". EV_STG_API_CONVERTED_CONTENT evCC = arch. arch. The property is read/write.134 Content Management API IArchive :: Description Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.Name = "my new archive". IArchive :: Description This property contains a more complete description of the archive. or the object is already populated. [out] arch. CONVERTED_CONTENT_STORED. . arch. uint itemCount = (uint) arch.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.Description = "my new archive description".IndexUrgency = EV_STG_API_INDEX_URGENCY.Size.ExpireItems. retval] BSTR* pVal) Parameters [in] BSTR newVal Description of the archive. If supplied.create archive //then check name archive->get_ Description (&bstr). Return value S_OK Success. Max length: 127 characters.retval] BSTR* Pointer to a BSTR that will contain the description of the archive. Any attempt to change the description of an existing archive will result in an error. The property is optional. //try changing name 135 . or the object is already populated. pVal Remarks The [in] property can only be used to set the description of a new archive before it is created. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.Content Management API IArchive :: Description Syntax HRESULT Description([in] BSTR newVal) HRESULT Description([out. [out. archive->put_Description(bstr): //do something . Examples [C++] CComBstr bstr = new CComBSTR(L"archive description"). the value must contain printable characters only. newVal contains invalid characters. The property is read/write. Description. Syntax HRESULT ExpireItems([out.136 Content Management API IArchive :: ExpireItems bstr = L"New description". HRESULT ExpireItems([in] EV_STG_API_EXPIRE_ITEMS newVal). archive->put_ Description (bstr). Description = "New description". Remarks The required value must be set prior to calling Create. //do something . Description = "archive description". [in] EV_STG_API_EXPIRE_ITEMS newVal Sets a new value of ExpireItems.create archive //then check name string name = archive. //try changing name archive. retval] EV_STG_API_EXPIRE_ITEMS* pVal Pointer to an EV_STG_API _EXPIRE_ITEMS object that will contain the current value. Parameters [out. //ERROR IArchive :: ExpireItems This property specifies whether or not items should be automatically deleted (expired) from the archive. . retval] EV_STG_API_EXPIRE_ITEMS* pVal). //ERROR [C#] archive. ExpireItems = ei. archive->put_ExpireItems(ei). Return value S_OK Success. //ERROR [C#] EV_STG_API_EXPIRE_ITEMS ei = EV_STG_API_EXPIRE_ITEMS. archive. newVal is invalid. //try changing value archive->put_ExpireItems(EXPIRE_ITEMS). as an error will occur. //do other things and create archive //Now check value archive->get_ExpireItems(&ei).Content Management API IArchive :: ExpireItems The [in] property can only be used to set the ExpireItems value of a new archive before it is created. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. Do not attempt to retrieve a value for ExpireItems before creating or getting an archive. It may be necessary to cast this to an integer if using in C#. EV_STG_API_EXPIRE_ITEMS is an enumeration type that indicates whether expired items should be deleted automatically from the archive. Any attempt to change this value in an existing archive will result in an error. //do other things and create archive 137 . or the object is already populated. See “EV_STG_API_EXPIRE_ITEMS enumeration” on page 81. No default value is set for this property. Examples [C++] EV_STG_API_EXPIRE_ITEMS ei = DONT_EXPIRE_ITEMS.DONT_EXPIRE_ITEMS. //try changing value archive. HRESULT ConvertedContent([in] EV_STG_API_CONVERTED_CONTENT newVal). [in] EV_STG_API_CONVERTED_CONTENT newVal The new value of ConvertedContent. The property is read/write. Any attempt to change this value on an existing archive will result in an error.ExpireItems = EV_STG_API_EXPIRE_ITEMS. retval] EV_STG_API_CONVERTED_CONTENT* pVal). Any attempt to retrieve the value of this property before Get or Create has been called will result in an error.EXPIRE_ITEMS.138 Content Management API IArchive :: ConvertedContent //Now check value ei = archive. retval]EV_STG_API_CONVERTED_CONTENT* pVal Pointer to an EV_STG_API_ CONVERTED_CONTENT object that will contain the current value.ExpireItems. Remarks This property must be set before calling Create. See “EV_STG_API_CONVERTED_CONTENT enumeration” on page 79. //ERROR IArchive :: ConvertedContent This property specifies whether converted content is stored in the item or generated on demand. . Syntax HRESULT ConvertedContent([out. EV_STG_API_CONVERTED_CONTENT enumeration indicates whether to store converted content with the item. Parameters [out. ConvertedContemt = cc. //do other things and create archive //Now check value archive->get_ConvertedContent(&cc). //do other things . //ERROR [C#] EV_STG_API_CONVERTED_CONTENT cc = EV_STG_API_CONVERTED_CONTENT. //try and change value archive->put_ConvertedContent(CONVERTED_CONTENT_ON_DEMAND).ConvertedContent = EV_STG_API_CONVERTED_CONTENT.ConvertedContent. archive->put_ConvertedContent(cc).CONVERTED_CONTENT_STORED. or the object is already populated.CONVERTED_ON_DEMAND. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. newVal is invalid. //ERROR 139 . //try and change the value archive.create archive //check value cc = Archive. Examples [C++] EV_STG_API_CONVERTED_CONTENT cc = CONVERTED_CONTENT_STORED.Content Management API IArchive :: ConvertedContent Return value S_OK Success. archive. The property is read/write. Parameters [out. Syntax HRESULT IndexUrgency([out. 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. the items will not be indexed until the value has been reset to IMMEDIATELY. HRESULT IndexUrgency([in] EV_STG_API_INDEX_URGENCY newVal). See “EV_STG_API_INDEX_URGENCY enumeration” on page 82.140 Content Management API IArchive :: IndexUrgency IArchive :: IndexUrgency This property specifies when items are indexed. 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. retval] EV_STG_API_INDEX_URGENCY* pVal). and the next time the Indexing Service runs it will process the index backlog. If this value is set. Return value S_OK Success. EV_STG_API_INDEX_URGENCY enumeration indicates whether to index items as they are stored. . //ERROR 141 . newVal is invalid. //ERROR [C#] EV_STG_API_INDEX_URGENCY iu = EV_STG_API_INDEX_URGENCY. IndexUrgency . IndexUrgency = EV_STG_API_INDEX_URGENCY. //do more and create archive //Now check value archive->get_ IndexUrgency (&iu). //do other things .INDEX_ITEMS_IMMEDIATELY.Content Management API IArchive :: IndexUrgency CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. //try and change value archive->put_ IndexUrgency (INDEX_ITEMS_DEFER_INDEFINITELY). //try and change the value archive. archive->put_IndexUrgency(iu). or the object is already populated. Examples [C++] EV_STG_API_INDEX_URGENCY iu = INDEX_ITEMS_IMMEDIATELY. . archive.INDEX_ITEMS_DEFER_INDEFINITELY.create archive //check value iu = Archive.IndexUrgency = iu. Syntax HRESULT IndexLevel([out. [in] EV_STG_API_INDEX_LEVEL newVal New value of EV_STG_API_ INDEX_LEVEL. HRESULT IndexLevel([in] EV_STG_API_INDEX_LEVEL newVal). When users search the archives to which they have access. Parameters [out. The Indexing service manages the indexes of archived data to enable users to search for archived items. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. newVal is invalid. the more information that is indexed about an item. Remarks EV_STG_API_INDEX_LEVEL enumeration indicates how much of an item is indexed. The property is read/write. or the object is already populated. the more disk space is required for the index. the quicker it is to find the item. Return value S_OK Success.142 Content Management API IArchive :: IndexLevel IArchive :: IndexLevel This property determines the level of detail stored in the archive's index. See “EV_STG_API_INDEX_LEVEL enumeration” on page 81. retval] EV_STG_API_INDEX_LEVEL* pVal). . retval] EV_STG_API_INDEX_LEVEL* pVal Pointer to an EV_STG_API_ INDEX_LEVEL object that will contain the current value. However. the index volume files are searched. The more information that is indexed about an item. INDEX_LEVEL_BRIEF. //try and change value archive->put_ IndexLevel (INDEX_LEVEL_FULL). IndexLevel = il. //ERROR [C#] EV_STG_API_INDEX_URGENCY il = EV_STG_API_INDEX_LEVEL.create archive //check value il = Archive. //try and change the value archive. IndexLevel. The property is read only. archive. //do something .Content Management API IArchive :: Size Examples [C++] EV_STG_API_INDEX_LEVEL il = INDEX_LEVEL_BRIEF. archive->put_IndexLevel(il). IndexLevel = EV_STG_API_INDEX_LEVEL. 143 . INDEX_LEVEL_FULL. //do something and create archive //Now check value archive->get_ IndexLevel (&il). //ERROR IArchive :: Size This property contains the size of the archive. Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. EV_STG_API_INDEX_LEVEL evIL = arch. Remarks Property will only contain a value once an archive has been created. or the object has not been populated. arch. arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".ConvertedContent.IndexUrgency. retval] VARIANT* pVal).IndexLevel. EV_STG_API_INDEX_URGENCY evIU = arch.Size. 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 VT type is a VT_U18. The request should be retried later. expressed in Kbytes.Description.Name. retval] VARIANT* pVal Pointer to a VARIANT that will contain the size of the archive.144 Content Management API IArchive :: Size Syntax HRESULT Size([out.ExpireItems. Parameters [out. EV_STG_API_EXPIRE_ITEMS evEI = arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".Get(). EV_STG_API_CONVERTED_CONTENT evCC = arch. . Example arch. string description = arch. ulong size = (ulong) arch. string name = arch. A read/write version of the property is available on the IArchive3 interface. For example. IArchive :: SecurityDescriptor This property contains the self-relative security descriptor to be used when creating an archive. Parameters [in] VARIANT newVal New value of the security descriptor. EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security descriptor permissions for an archive. The values of the EV_STG_API_PERMISSIONS_TYPE enumeration may be combined (using OR) to set the required value. Syntax HRESULT SecurityDescriptor([in] VARIANT newVal). See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 85. the user creating the archive has full access to the archive).Content Management API IArchive :: SecurityDescriptor bool complianceDevice = arch. Finally a type of VT_NULL means that the archive is created without any permissions. you would enter PERMISSIONS_SEARCH|PERMISSIONS_READ. The property is write only. Remarks Any attempt to modify the security descriptor of an existing archive will result in an error. 145 . 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. to set search and read item. If the type of the variant is VT_EMPTY then the security descriptor is set to default (that is.ItemCount. The self-relative security descriptor may override the current user. uint itemCount = (uint) arch.ComplianceDevice. wcout << L"Domain\\Account: " << flush. // Create Security Identifier from Domain and Account CSid Sid. SecurityDesc. // Copy security descriptor to a byte array UINT SecurityDescLength = SecurityDesc. if (!Sid. this property is superseded by the IArchive3::SecurityDescriptor property.LoadAccount(aszPrompt)) { return HRESULT_FROM_WIN32(GetLastError()). PERMISSIONS_READ_WRITE_DELETE)) { return HRESULT_FROM_WIN32(GetLastError()). See “IArchive3 :: SecurityDescriptor” on page 157.getline(aszPrompt. Return value S_OK Success. cin. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER newVal is invalid.AddAllowedAce(Sid.SetDacl(Dacl). or the object is already populated. Example To create a security descriptor: char aszPrompt[MAX_INPUT_BUFFER].GetLength(). .MakeSelfRelative(). // Convert security descriptor to self-relative format SecurityDesc. MAX_INPUT).146 Content Management API IArchive :: SecurityDescriptor Version information At Enterprise Vault 8.0. } // Create ACE (access-control entry) CDacl Dacl. } // Set information in a DACL (discretionary access-control list) CSecurityDesc SecurityDesc. if (!Dacl. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. Syntax HRESULT ComplianceDevice([out. Return value S_OK Success. SecurityDescriptor->parray = SecurityDescSafeArrayOfBytes. (BYTE*)pSecurityDesc). SecurityDescriptor->vt = vt. VARTYPE vt = SecurityDescSafeArrayOfBytes. retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which will contain the current value. 147 .GetPSECURITY_DESCRIPTOR(). otherwise an error will result. IArchive :: ComplianceDevice This property tells the caller whether the archive resides on a device capable of setting compliance periods. Get must be called before accessing this property. Parameters [out. Remarks If the archive is on a compliance device then TRUE is returned.Detach(). or the object has not been populated.Add(SecurityDescLength. hr = SecurityDescSafeArrayOfBytes. The property is read only. retval] VARIANT_BOOL* pVal).GetType(). vt = vt | VT_ARRAY. CComSafeArray<BYTE> SecurityDescSafeArrayOfBytes. otherwise FALSE is returned.Content Management API IArchive :: ComplianceDevice const SECURITY_DESCRIPTOR *pSecurityDesc = SecurityDesc. ConvertedContent. The property is read only.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".ExpireItems. string name = arch. EV_STG_API_CONVERTED_CONTENT evCC = arch. uint itemCount = (uint) arch. EV_STG_API_INDEX_URGENCY evIU = arch. Example arch. bool complianceDevice = arch. The request should be retried later.ComplianceDevice.IndexLevel.retval] VARIANT* pVal Pointer to a VARIANT that will contain the current number of items in the archive.Description.Size.Get(). CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. EV_STG_API_EXPIRE_ITEMS evEI = arch. IArchive :: ItemCount This property tells the caller how many items are currently held in the archive.148 Content Management API IArchive :: ItemCount CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.Name. arch. .Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". EV_STG_API_INDEX_LEVEL evIL = arch.retval] VARIANT* pVal) Parameters [out.IndexUrgency. string description = arch. arch. ulong size = (ulong) arch.ItemCount. Syntax HRESULT ItemCount([out. Size.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". The type of the variant will be unsigned long. string description = arch.Name. for example. vt= VT_UI4. .ConvertedContent. IArchive :: Create This method is used to create an archive. arch.Description.IndexLevel. arch. or the object has not been populated. EV_STG_API_INDEX_URGENCY evIU = arch. EV_STG_API_EXPIRE_ITEMS evEI = arch. ulong size = (ulong) arch. EV_STG_API_INDEX_LEVEL evIL = arch. uint itemCount = (uint) arch. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.Content Management API IArchive :: Create 149 Remarks This property can only be used after Get or Create have been called. bool complianceDevice = arch. EV_STG_API_CONVERTED_CONTENT evCC = arch. 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.ItemCount.IndexUrgency.Get().VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".ComplianceDevice. string name = arch. Example arch. Return value S_OK Success. .ExpireItems. The request should be retried later. or the object is already populated. Return value S_OK Success. Before calling this method. ‘Can manage Enterprise Vault Stores’. By default. See “IArchive3 :: Type” on page 162. 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. it is always created as an Enterprise Vault shared archive. . When an archive is created.150 Content Management API IArchive :: Create Syntax HRESULT Create(void) Remarks To create an archive the calling application must be in a role that includes the operation. an invalid combination of properties has been set. the Id property will be populated with the archive Id from the Enterprise Vault Directory. the Enterprise Vault Storage Administrator and Power Administrator roles include this operation. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One or more of the mandatory properties have not been set. Name = "XYZRM_" + userName. Examples [C++] archiveName = L"XYZRM_". archive->put_IndexLevel(INDEX_LEVEL_FULL).EXPIRE_ITEMS. 151 . ‘Can manage Enterprise Vault Stores’. archive->put_Description(CComBSTR(L"XYZ RM application archive")).VaultStoreId = "181E669473B52E64384C9A7D9EACA0E7E1210000evsite". archive->put_IndexUrgency(INDEX_ITEMS_IMMEDIATELY). // Remember the assigned Id for future insertions [C#] archive. CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller not in a role that includes the operation.ExpireItems = EV_STG_API_EXPIRE_ITEMS. archive->put_ConvertedContent(CONVERTED_CONTENT_STORED). archive. archive->Create().Description = "XYZ RM application archive". The request should be retried later. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. archive->put_Name(archiveName). archive->put_ExpireItems(EXPIRE_ITEMS). archiveName += username.Content Management API IArchive :: Create CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. archive. archive. archive->get_Id(&archiveId). archive->put_VaultStoreId(CComBSTR(L"181E669473B52E64384C9A7D9EACA0 E7E1210000evsite")). (The default Enterprise Vault Storage Administrator and Power Administrator roles include this operation). INDEX_LEVEL_FULL. archive. CONTENTMANAGEMENTAPI_E_NOT_FOUND The archive does not exist. Before calling this method. archive. The request should be retried later. populating the properties of the object.Id.IndexUrgency =EV_STG_API_INDEX_URGENCY.CONVERTED_CONTENT_STORED. the ArchiveId must be set. Example arch.IndexLevel = EV_STG_API_INDEX_LEVEL. archive.ConvertedContent = EV_STG_API_CONVERTED_CONTENT. Return value S_OK Success.152 Content Management API IArchive :: Get archive. . archiveId = archive. // Remember the assigned Id for future insertions IArchive :: Get This method is used to retrieve information about an archive.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". Syntax HRESULT Get(void) Remarks The Get method tells the Content Management API to retrieve archive details from the store.Create(). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Id property is empty. 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.INDEX_ITEMS_IMMEDIATELY. Parameters [out. EV_STG_API_EXPIRE_ITEMS evEI = arch. SharePoint archive. FSA archive. Remarks EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive. IArchive2 :: Type This property identifies the type of the archive. this property is superseded by the IArchive3::Type property.ItemCount.ComplianceDevice. uint itemCount = (uint) arch. EV_STG_API_CONVERTED_CONTENT evCC = arch. EV_STG_API_INDEX_LEVEL evIL = arch. The property is read only.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". arch.Name.Size.ExpireItems. Version information At Enterprise Vault 8. bool complianceDevice = arch. Syntax HRESULT Type([out. for example.Description.0. string description = arch. and so on. See “IArchive3 :: Type” on page 162.IndexUrgency. See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 77. 153 . ulong size = (ulong) arch. EV_STG_API_INDEX_URGENCY evIU = arch. retval] EV_STG_API_ARCHIVE_TYPE* pVal Pointer to an EV_STG_API _ARCHIVE_TYPE that contains the current value. string name = arch.IndexLevel. Exchange Server mailbox archive.Get(). retval] EV_STG_API_ARCHIVE_TYPE* pVal).ConvertedContent.Content Management API IArchive2 :: Type arch. Get(). arch2.Status. Syntax HRESULT Status([out. retval] EV_STG_API_STATUS* pVal Remarks EV_STG_API_STATUS enumeration indicates the status of the archive. IArchive2 :: Status This property indicates the status of the archive.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". whether it can be accessed. that is. The property is read only. . arch2.Archive2. See “EV_STG_API_STATUS enumeration” on page 86. Example IArchive2 arch2 = cmAPI. retval] EV_STG_API_STATUS* pVal). Return value S_OK Success CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.154 Content Management API IArchive2 :: Status Return value S_OK Success CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. Parameters Pointer to an EV_STG_API _STATUS that contains the current value. [out.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". arch2. EV_STG_API_STATUS evStatus = arch2. The property is read only. retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL that contains the current value.Archive2. Remarks In Enterprise Vault some types of archive. such as shared or journal archives. Syntax HRESULT HasFolders([out. if (hasFolders == true) 155 . arch2. arch2. bool hasFolders = arch2. Parameters [out. Example IArchive2 arch2 = cmAPI.HasFolders.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". cannot contain folders. STS_AVAILABLE) { //store some items IArchive2 :: HasFolders This property indicates whether the archive is flat or contains a folder structure. Return value S_OK Success CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.Content Management API IArchive2 :: HasFolders if (evStatus == EV_STG_API_STATUS. retval] VARIANT_BOOL* pVal).Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". bool full = arch2. Return value S_OK Success CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. Example IArchive2 arch2 = cmAPI.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite".156 Content Management API IArchive2 :: Full { //do something IArchive2 :: Full This property indicates whether the archive is full. no more items can be stored in it. arch2. Syntax HRESULT Full([out. Parameters [out. The property is read only.Archive2. retval] VARIANT_BOOL* pVal). if (!full) { //store some items . retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL that contains the current value. arch2.Full. Remarks If the archive is full.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". IArchive3 :: SecurityDescriptor This property contains the self-relative security descriptor associated with an existing archive. 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.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". Remarks When configuring Enterprise Vault. or to be used when creating an archive. arch.Archive2.DirectoryDNSAlias. Example IArchive2 arch2 = cmAPI. retval] BSTR* pVal). Syntax HRESULT DirectoryDNSAlias([out. The property is read only. string dnsAlias = arch2.Content Management API IArchive2 :: DirectoryDNSAlias IArchive2 :: DirectoryDNSAlias This property contains the DNS Alias created for the Enterprise Vault Site. Return value S_OK Success CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. Parameters [out.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". This property represents the manually set permissions of the archive. arch. retval] BSTR* pVal Pointer to a string containing the current DNS alias for the Enterprise Vault Site. which are displayed on the Permissions tab of the archive properties dialog in the Enterprise Vault Administration Console. 157 . We recommend that you use the SecurityDescriptorString property to retrieve and set the security descriptor from applications. HRESULT SecurityDescriptor([in] VARIANT newVal). If the type of the variant is VT_NULL. then the archive is created without any permissions. If the type of the variant is VT_EMPTY then the security descriptor is set to default (that is. Return value S_OK Success.158 Content Management API IArchive3 :: SecurityDescriptor The property is read/write. The values are logically OR'd to get the combined permissions. retval] VARIANT* pVal). newVal is invalid. See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 85. Remarks If the type of the variant is VT_ARRAY. [in] VARIANT newVal New value of the security descriptor. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. Syntax HRESULT SecurityDescriptor([out. Any attempt to modify the security descriptor of an existing archive will result in an error. . See “IArchive3 :: SecurityDescriptorString” on page 159. then the variant is a byte array containing the SECURITY_DESCRIPTOR for the user account that will be given access to the archive. the user creating the archive has full access to the archive). retval] VARIANT pVal Pointer to a VARIANT structure that will hold the returned security descriptor value. or the object is already populated. EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security descriptor permissions for an archive. Parameters [out. [C++] CComPtr<IArchive> pArchive. // Get an instance of an IArchive3 object to populate pCmAPI->get_Archive(&pArchive). which are displayed on the Permissions tab of the archive properties dialog in the Enterprise Vault Administration Console. This property represents the manually set permissions of the archive. // Retrieve Archive information // pArchive3->Get(). } IArchive3 :: SecurityDescriptorString This property contains the security descriptor string associated with an existing archive. // Fetch the SecurityDescriptor property value associated with archive // CComVariant varSecurityDescriptor. CComQIPtr<IArchive3> pArchive3(pArchive). pArchive3->put_VaultStoreId(CComBSTR(L"181E669473B52E64384C9A7 D9EACA0E7E1210000evsite")).Content Management API IArchive3 :: SecurityDescriptorString Example This example illustrates how to fetch the SecurityDescriptor property value. The property is read/write. pArchive3->get_SecurityDescriptor(&varSecurityDescriptor). if (pArchive3 != NULL) { pArchive3->put_Id(CComBSTR(L"240A579483C52B89384A9D7D9EACA0E7E 9350000evsite"). or to be used when creating an archive. 159 . retval] BSTR* pVal).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. Remarks If specified. this property must be set before calling the Create archive method.. the ATL Library includes CSecurityDesc class with FromString method. functional security . then the user creating the archive is given full access to the archive. ■ If the supplied BSTR value is an empty (zero length) string. Parameters [in] BSTR newVal The security descriptor value formatted as a text string which conforms to the Security Descriptor string format. "O:AOG:DAD:(A. [out.microsoft. 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. which converts a string-format security descriptor into a valid.. Any attempt to change this value on an existing archive will result in an error.160 Content Management API IArchive3 :: SecurityDescriptorString Syntax HRESULT SecurityDescriptorString ([in] BSTR newVal).RPWPCCDCLCSWRCWDWOGA. For example.. then the archive is created without any permissions. HRESULT SecurityDescriptorString([out. retval] BSTR* pVal Pointer to a string that will hold the returned security descriptor value.com/en-us/library/aa379570. The value of the SecurityDescriptorString property must conform to the MSDN Security Descriptor String Format.S-1-0-0)". see the MSDN Security Descriptor String Format article: http://msdn. For information on how to create Security Descriptor strings. . CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.CCDCLCSW.Content Management API IArchive3 :: SecurityDescriptorString descriptor.... In addition. Security descriptor strings using .NET managed code String type and StringBuilder class are available for constructing the SecurityDescriptorString property values.CCDCLCSW.S-1-5-21-2986758783-3322231649-3643854221-1255)" The following example includes the access described in the first example above... and a ToString method.. and in addition a group have been denied full permissions access (Read+Write+Delete) on the archive: "D:(D. the ConvertStringSecurityDescriptorToSecurityDescriptor and ConvertSecurityDescriptorToStringSecurityDescriptor functions are available. newVal is invalid..... or the object is already populated.CCDCLCSW.CCDCLCSW... which converts a security descriptor to a string format..S-1-5-21-2457296135-1045600968-2011822662-6419)" 161 .S-1-5-21-2457296135-1045600968-2011822662-6419) (A. Return value S_OK Success. Examples The following security descriptor string indicates a user who has been granted full permissions access (Read+Write+Delete) to an archive: "D:(A.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. and in addition a group has been granted full permissions access ( Read+Write+Delete) on the archive: "D:(A..CCDCLCSW.S-1-5-21-2986758783-3322231649-3643854221-1255) (A. The following example includes the access described in the example above. SharePoint archive. True means that the archive is structured. Table 4-20 shows the implied values. Syntax HRESULT Type([in] EV_STG_API_ARCHIVE_TYPE newVal). False means that the archive is flat. HRESULT Type([out. See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 77. retval] EV_STG_API_ARCHIVE_TYPE* pVal Pointer to an EV_STG_API _ARCHIVE_TYPE that contains the current value. and so on. The property is read/write. The value of the property IArchive::HasFolders will be implied from the Type property value. retval] EV_STG_API_ARCHIVE_TYPE* pVal). for example. Parameters [in] EV_STG_API_ARCHIVE_TYPE newVal The new value of Type. [out. Exchange Server mailbox archive. Remarks Currently. FSA archive. any other value is treated as invalid. 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 .162 Content Management API IArchive3 :: Type IArchive3 :: Type This property identifies the type of the archive. newVal can only be set to ARCHIVE_TYPE_SHARED. 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. Name = "my new archive". ARCHIVE_TYPE_EXCHANGE_MAILBOX) { // do something [in] IArchive3 arch3 = cmAPI. arch3. arch3. arch3. arch3.Get().VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite". Example [out] IArchive3 arch3 = cmAPI. if (evType == EV_STG_API_ARCHIVE_TYPE.Archive3.Archive3. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. 163 .Type. newVal is invalid.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Description = "my new archive description". EV_STG_API_ARCHIVE_TYPE evType = arch3. arch3. the object is already populated.Content Management API IArchive3 :: Type Table 4-20 Structure of archive types (continued) EV_STG_API_ARCHIVE_TYPE value HasFolders property value ARCHIVE_TYPE_FILE_SYSTEM True ARCHIVE_TYPE_SHAREPOINT True ARCHIVE_TYPE_DOMINO_MAILBOX False ARCHIVE_TYPE_DOMINO_JOURNAL False Return value S_OK Success. Type = EV_STG_API_ARCHIVE_TYPE. arch3. arch3. StartSequenceNum Read/Write The starting item sequence number to be used when fetching a collection of item records. 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. . DONT_EXPIRE_ITEMS. CONVERTED_CONTENT_STORED.ExpireItems = EV_STG_API_EXPIRE_ITEMS. OrderBy The index sequence number ordering to be used when enumerating items in the collection. arch3. See Table 4-9 on page 108.164 Content Management API Items object arch3. ARCHIVE_TYPE_SHARED.Create(). INDEX_ITEMS_IMMEDIATELY. 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.IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL. arch3.ConvertedContent = EV_STG_API_CONVERTED_CONTENT. Read/Write The properties and methods of the ICollectionBase interface are described in later sections.IndexUrgency = EV_STG_API_INDEX_URGENCY. Items object This object implements the following interface: ■ IItems The IItems interface inherits the properties and methods of the ICollectionBase interface. arch. Item Read only Instance of the item at the zero-based index into the collection. Clear Clear the current collection. Table 4-23 ICollectionBase methods Method Description Get Populate the collection. _NewEnum Read only Instance of the standard COM enumerator for the collection. Table 4-22 ICollectionBase properties Property Read/Write Description Count Read only Number of items in the collection. Maximum Read/Write Maximum number of items in the collection. More Read only Whether or not there were more items than Maximum. Reset Reset the object back to the initial state. ■ IItem::Id ■ IItem::ArchiveId ■ IArchiveMetaData2::SequenceNum ■ IArchiveMetaData2::CurrentLocation ■ IArchiveMetaData2::CurrentFolderId ■ IArchiveMetaData::RetentionCategory ■ IItem::CopyOptions 165 . the Get method should be called specifying the required detail level. The following properties are populated for each Item object in the collection.Content Management API Items object See Table 4-10 on page 108. Remarks Calling applications must have at least Read access to the target archive. If additional properties are required for an Item. [C++] // Get empty items collection for populating CComPtr<IContentManagementAPI3> spCMAPI. Enable recovery of user deleted items.CreateInstance(CComBSTR(L"EnterpriseVault. spCMAPI. enumerates the required items in the target archive and retrieves details of the items from the Enterprise Vault Directory.SYM. CComPtr<IUnknown> spUnk.ContentManagement API")).000] (Comment: Ref ICollectionBase :: Maximum) .REA.0 or later. The soft delete functionality is enabled using the Enterprise Vault Administration Console. VARIANT_BOOL vbMore = VARIANT_TRUE. // Get an Items object for enumeration spCMapi->get_Items(&spUnk). by selecting the archive setting. // Populate the Items collection spItems->put_ArchiveId (CComBSTR("1C51F75FFC26EC840A012AD322C579 3AF1e10000LAGUNA4. CComQIPtr<IItems> spItems(spUnk). in Site properties.COM")). spItems->put_StartSequenceNum (1) // [Min = 1] spItems->put_Maximum(500) // [Max = 10.166 Content Management API Items object ■ IItem::DeletionLevel ■ IArchvieMetaData::ComplianceDevice ■ IArchiveMetaData::OverrideOnholdRetCat Populating these properties avoids the need to call Get to determine the source item information before calling CopyTo or MoveTo. Note that the items collection will not include items that have been soft deleted from the archive. ULONGLONG LastSequenceNum.RND. Example This example creates an Items collection object. if this has been enabled. Version information ■ This interface requires Enterprise Vault 8. &spUnk). CComPtr<IArchiveMetaData> spAMD. // Process each item in collection long lCount = 0.. spItems->get_Count(&lCount). (of previous collection) + 1 spItems->put_StartSequenceNum = LastSequenceNum+1. CComQIPtr<IItem> spItem(spUnk). no. . spItem->get_ArchiveMetaData(&spAMD). ++idx) { CComPtr<IUnknown> spUnk.Content Management API Items object spItems->put_OrderBy(ITEMS_ORDERBY_ASC) // Ascending do { CComPtr<IItem> spItem. // Iterative loop for(long idx = 0. // Fetch next chunk of items if (vbMore) { // Reset start sequence no to last item's sequence no. 167 .. CComQIPtr<IArchiveMetaData2> spAMD2(spAMD). idx < lCount. // Fetch a batch of items spItems->Get(). //Do something spItem->Get(DETAIL_LEVEL_ITEM_CONTENT | DETAIL_LEVEL_ARCHIVE_METADATA). //Fetch item spItems->get_Item(idx. // Remember the last item seq. spAMD2->get_SequenceNum(&LastSequenceNum) } vbMore = spItems->More(). The following gives an example value of the ArchiveId property: "181E669473B52E64384C9A7D9EACA0E7E1110000evsite" . archives and items” on page 70. ■ See “Item object” on page 172. as this identifies both the archive and the archive folder. HRESULT ArchiveId([out. Maximum length of string: 127 characters. ■ See “ICollectionBase : IDispatch” on page 308. IItems :: ArchiveId This property identifies the archive in which the required items are stored. [out. Remarks Note that the value used can be either the Archive ID or the ID of a folder in the archive. Parameters [in] BSTR newVal The ID of the target archive.168 Content Management API IItems :: ArchiveId } } while (vbMore) See also ■ See “Enumerating vault stores. ■ See “ArchiveMetaData object” on page 225. retval] BSTR* pVal Pointer to a BSTR that will contain the ID of the current archive. ■ See “Content object” on page 212. The property is read/write. Syntax HRESULT ArchiveId([in] BSTR newVal). retval] BSTR* pVal). The Archive ID is displayed in the properties of the archive in the Administration Console. StartSequenceNum = 1000. Syntax HRESULT StartSequenceNum([in] ULONGLONG newValue).Content Management API IItems :: StartSequenceNum 169 Return value S_OK Success. items.OrderBy = EV_API_ITEMS_ORDERBY. The property is read/write.Items.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". .ITEMS_ORDERBY_ASC.Get(). Parameters [in] ULONGLONG newValue Index sequence number of the first item in the required items collection. [out. items. Example IContentManagementAPI4 cmAPI4 = new agementAPIClass(). (IContentManagementAPI4)ContentMan IItems items = cmAPI4. IItems :: StartSequenceNum This property specifies the Index Sequence Number (ISN) of the first item in the items collection. HRESULT StartSequenceNum([out. items. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is not a valid archive identity.retval] ULONGLONG* pVal). items.retval] ULONGLONG* pVal Integer that will receive the index sequence number of the first item in the collection. StartSequenceNum = 1000. See “IArchiveMetaData2 :: SequenceNum” on page 253.NET managed code and C++ support ULONGLONG types. items. This property can be used to determine the start Index Sequence Number for the collection enumeration. items. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is not a valid archive identity. . Enterprise Vault item sequence numbers are not always consecutive. Return value S_OK Success. The property is read/write. The default value for this property is 1. as items may have expired or been deleted. IItems :: OrderBy This property is used to specify the index sequence number order to be used when enumerating items in the collection. IItems items = cmAPI3.ITEMS_ORDERBY_ASC.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". Requirements Windows Server 2003 supports ULONGLONG types with OLE Automation. Example IContentManagementAPI3 cmAPI3 = new (IContentManagementAPI3)ContentManagementAPIClass(). items.170 Content Management API IItems :: OrderBy Remarks The Index Sequence Number of an archived item is specified in the IArchiveMetaData2::SequenceNum property. However ULONGLONG types are not supported on Windows Server 2000.Items. items. .Get().OrderBy = EV_API_ITEMS_ORDERBY. but these types are not supported by Visual Basic Script. HRESULT OrderBy[out. Parameters [in] EV_API_ITEMS_ORDERBY newVal The index sequence number order to use when enumerating the item collection. .OrderBy = EV_API_ITEMS_ORDERBY. [out. items. IItems items = cmAPI4. items. See “EV_API_ITEMS_ORDERBY enumeration” on page 76. items. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is invalid.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Items.retval] EV_API_ITEMS_ORDERBY* pVal).StartSequenceNum = 1000. items. Remarks The default is to order by ascending index sequence number (ITEMS_ORDERBY_ASC). Return value S_OK Success.Get().retval] EV_API_ITEMS_ORDERBY* pVal The index sequence number order used when enumerating the current item collection.Content Management API IItems :: OrderBy 171 Syntax HRESULT OrderBy([in] EV_API_ITEMS_ORDERBY newVal).ITEMS_ORDERBY_ASC. Example IContentManagementAPI4 cmAPI4 = new (IContentManagementAPI3)ContentManagementAPIClass(). The IItem3 interface provides an additional method to recover an item that has been soft-deleted. or has been archived. . The IItem2 interface provides an additional property to help determine why an item no longer exists in an archive. or has been archived. 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. BrowserViewURL Read only URL for viewing the archived item. ArchiveMetaData Read only Pointer to an IArchiveMetaData object that provides details of how the item will be. Content Read only Instance of a Content object that provides access to the data that is to be archived. Id Read/Write Identifier of the item in the archive.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. DeletionLevel Read/Write Indicates whether deleting the item deletes it completely (hard delete) or moved to the Enterprise Vault "dumpster" (soft delete). Table 4-25 IItem methods Methods Description Get Retrieves archived item.Content Management API Item object Table 4-24 Property IItem properties (continued) Read/Write Description DefaultMSGFormat Read/Write Sets the format (ANSI or Unicode) for the item being retrieved. NativeItemURL Read only URL for downloading the archived item. CopyOptions Read/Write Identifies source item property values to be copied to the destination item. MoveTo Move archived item to another location. 173 . The item is opened in the default application for the type of item. or information about an archived item. Holds Read only Enables the enumeration of legal holds placed on the archived item. Delete Delete item from archive. Table 4-26 IItem2 property Property Read/write Description DeletionReason Read only If the item no longer exists in the archive. where the original format has not been stored. CopyTo Copy archived item to another location. CanBeDeleted Check if archived item can be deleted. Insert Stores item in an archive. this property can be used to discover why the item was deleted. Example IItem item = cmAPI. item. . ■ IItem2 interface requires Enterprise Vault 8. item. or to be stored. HRESULT ArchiveId([in] BSTR newVal).0 SP3.DETAIL_LEVEL_ITEM_PROPERTIES).0. Parameters [in] BSTR newVal The Archive ID of the archive. Remarks After the Create or Get method has been called on this interface.0. item. Maximum length of string: 127 characters. ■ IItem3 interface requires Enterprise Vault 9.Item. Version information ■ CopyOptions property requires Enterprise Vault 8. The property is read/write.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".174 Content Management API IItem :: ArchiveId Table 4-27 IItem3 method Property Description Undelete Recover an item that has been soft-deleted. Syntax HRESULT ArchiveId([out. retval] BSTR* pVal). the current interface pointer must be released and a new one obtained before calling either of these methods again.Get((int)EV_STG_API_ITEM_DETAIL. IItem :: ArchiveId This property identifies the archive in which the item is stored. itm.ArchiveId = ""181E669473B52E64384C9A7D9EACA0E7E1110000evsite".DETAIL_LEVEL_ITEM_PROPERTIES). retval] BSTR* pVal Pointer to a BSTR that will contain the ID of the current archive. An error will result if an attempt is made to change the value of an existing item. Remarks Note that the value used can be either the Archive ID or the ID of a folder in the archive.Get((int)EV_STG_API_ITEM_DETAIL. itm. retval] BSTR* pVal). The following gives an example value of the ArchiveId property: "181E669473B52E64384C9A7D9EACA0E7E1110000evsite" Return value S_OK Success. Example [C#] IItem itm = cmAPI. itm.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7 9f3298dc8a1e60". Syntax HRESULT Id([out. This value is displayed in the properties of the archive in the Administration Console.Content Management API IItem :: Id [out. HRESULT Id([in] BSTR newVal). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. as this identifies both the archive and the archive folder.Item. or newVal is not a valid Archive Id. This property is read/write. This property must be set before calling Get. IItem :: Id This property identifies the item in the archive. 175 . This property can hold the item's Transaction ID or Saveset ID. The default value (NULL) is returned. See “Saveset IDs and Transaction IDs” on page 71. as this will result in an error.176 Content Management API IItem :: Id Parameters [in] BSTR newVal Id of stored item.retval] BSTR* pVal Pointer to a BSTR that will contain the current value of this item's ID. Return value S_OK Success. It should not be set before calling an Insert method. Examples [C++] CComBSTR bstr(L"161000000000000~200501051649270000~0~9039eb282e3d4 083b79f3298dc8a1e60") . Version information Enterprise Vault 7. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. and must be set before calling the Get method. Remarks This property sets or retrieves the identifier of the item in the archive. or an attempt has been made to set the Saveset ID of an existing item. S_FALSE Success.0 or later is required to support a Transaction ID value for this property. [out. Any attempt to change the value of an existing item will result in an error. It is only populated once an item has been stored in an archive. or newVal is not a valid Saveset ID or Transaction ID. itm. however.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7 9f3298dc8a1e60". The interface pointer to IContent is read only. Each of these is described in more detail in the relevant section. ■ Title ■ OriginalLocation ■ FileExtension 177 . Remarks The IContent interface makes the following properties available. Syntax HRESULT Content([out. to be modified.Get((int)EV_STG_API_ITEM_DETAIL. //DO Get and check the id bstr. itm. retval] IContent** pVal).Clear(). the methods and properties exposed by IContent allow the content. Parameters [out.Archive.Content Management API IItem :: Content item->put_Id(bstr).DETAIL_LEVEL_ITEM_PROPERTIES). or has been archived (depending on when it is used). IItem :: Content This property returns an instance of a Content object that gives access to the data that is to be archived.retval] IContent** pVal Instance of a Content object. including the item data.Item. item->get_Id(&bstr).Id = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". [C#] IItem item = cmAPI. item. The property is read only. The property is read only. . Syntax HRESULT ArchiveMetaData([out. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. item.178 Content Management API IItem :: ArchiveMetaData ■ MimeFormat ■ CreatedDate ■ ModifiedDate ■ Data ■ OriginalSize ■ Author See “Content object” on page 212. the methods and properties exposed by IArchiveMetaData allow the metadata to be modified. IContent content= item.Content. item->get_Content(&pContent). LogContentProperties(content.DETAIL_LEVEL_ITEM_PROPERTIES). [C#] item. However. retval] IArchiveMetaData** pVal). Return value S_OK Success. IItem :: ArchiveMetaData This property returns a pointer to an IArchiveMetaData interface that provides details of how the item will be or has been archived. The interface pointer to IArchiveMetaData is read only.Id). Examples [C++] IContent* pContent = NULL.Get((int)EV_STG_API_ITEM_DETAIL. ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".retval] IArchiveMetaData** pVal Pointer to an IArchiveMetaData pointer. such as the assigned Retention Category and the date and time when the item was archived.Item.Content Management API IItem :: BrowserViewURL Parameters [out. Return value S_OK Success. item.retval] BSTR* pVal) 179 . DETAIL_LEVEL_ARCHIVE_METADATA). The property is read only. item. See also ■ See “ArchiveMetaData object” on page 225. IItem :: BrowserViewURL This property returns a string containing the URL that should be entered into a web browser (for example) to view the item. Syntax HRESULT BrowserViewURL([out. Example IItem item = cmAPI. item. Each of these is described in more detail in the relevant section. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL. See “ArchiveMetaData object” on page 225.Get((int)EV_STG_API_ITEM_DETAIL.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ArchiveMetaData. IArchiveMetaData amd = item. Remarks The IArchiveMetaData interface makes available properties that hold information about the item. Examples [C++] CComBSTR bstr. The request should be retried later. The URL returned includes the IIS virtual directory for the Enterprise Vault Web access application. item->put_Id(L"161000000000000~200501051649270000~0~9039eb282e3d408 3b79f3298dc8a1e60"). Return value S_OK Success. Remarks This property will return an error if the archive Id and item Id have not been set previously. Enterprise Vault dynamically generates the full URL as needed. item->put_ArchiveId("181E669473B52E64384C9A7D9EACA0E7E1110000evsi .retval] BSTR* pVal Pointer to a BSTR that will contain the URL. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. but not a specific Web server name. This form of URL is compatible with Enterprise Vault Building Blocks architecture. with the appropriate server name for each caller. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory Service is not running. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Either the Archive Id or Saveset Id have not been set or the Saveset Id is invalid.180 Content Management API IItem :: BrowserViewURL Parameters [out. [out. See Remarks below. where the original format has not been stored with the saveset.Id = "161000000000000~200501051649270000~0~9039eb282e3d4 083b79f3298dc8a1e60".BrowserViewURL. Remarks The following values can be assigned to newVal: "N" Perform no conversion. Parameters [in] BSTR newVal New value to be set. For example. [C#] item.Content Management API IItem :: DefaultMSGFormat te"). String url = Item. HRESULT DefaultMSGFormat([out. The property is optional. Item. IItem :: DefaultMSGFormat This property allows the caller to set the format as ANSI or Unicode for the item being retrieved. "U" Return as Unicode. item->get_BrowserViewURL(&bstr). Syntax HRESULT DefaultMSGFormat([in] BSTR newVal). 181 . "A:932" return as Japanese ANSI.retval] BSTR* pVal). "A:" Return as ANSI code page.arhiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite".retval] BSTR* pVal Pointer to a BSTR that will hold the current value. this means that items archived prior to Enterprise Vault 6. On a system with messages archived using an earlier release than Enterprise Vault 6. irrespective of the value of DefaultMSGFormat. items archived using File System Archiving. then no conversion is performed and the archive format is used. The value set for DefaultMSGFormat.set ids etc // ERROR . where the original format has not been stored with the saveset. However.0 SP1 are returned in Unicode format. Itm->put_DefaultMSGFormat(L"N"). In addition. then this property will return null.182 Content Management API IItem :: DefaultMSGFormat DefaultMSGFormat allows the caller to set the default format as ANSI or Unicode for the item being retrieved. If details of the original format were stored. Return value S_OK Success. If a value has not been explicitly set. items are stored in Enterprise Vault as Unicode. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.DefaultMSGFomart = "U". //do something .0 SP1 are returned in ANSI format. will be applied to any such items that do not have the original format recorded. //do something. SharePoint archiving. then the item will always be returned in its original format. If no value is specified for DefaultMSGFormat. items stored using Exchange Server archiving tasks (or PST migration) do not record details of the original format. put ids etc Item->Get(DETAIL_LEVEL_ALL).0 SP1. or an attempt has been made to change an existing value. Examples [C++] item->put_DefaultMSGFormat(L"U").0 SP1. [C#] itm. store details of the original format with the saveset. From Enterprise Vault 6. or API methods. and items archived since the upgrade to Enterprise Vault 6. ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". item.DETAIL_LEVEL_ALL)). Example IItem item = cmAPI. each of which defines a hold placed on the particular item.=defaultMSGFormat = "N". See “IItem :: Get” on page 194.Get method with the DETAIL_LEVEL_HOLD_DATA flag set prior to calling this property.Content Management API IItem :: Holds Itm. The property is read only.retval] IHolds** pVal Pointer to an IHolds pointer which will contain the current IHolds pointer. This property is a collection of IHold pointers. Syntax HRESULT Holds([out. Return value S_OK Success. each of which defines a hold placed on the particular item. or could not find the HOLDS collection. Parameters [out.retval] IHolds** pVal). See “Holds object” on page 285. 183 . Remarks This property is a collection of IHold pointers.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". //ERROR IItem :: Holds This property gives access to the set of holds currently placed on the item. Itm.Item. item.Get((int)(EV_STG_API_ITEM_DETAIL. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. The caller must have called the IItem. 184 Content Management API IItem :: NativeItemURL item. but not a specific Web server name. Parameters [out. or either the Item Id or Archive Id have not been set. This form of URL is compatible with Enterprise Vault Building Blocks architecture. Remarks There will be an error if either the item Id or the archive Id have not been set before using this property. retval] BSTR* pVal A pointer to a BSTR that will contain the current value. 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. IHolds holds = Item. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. Syntax HRESULT NativeItemURL([out. retval] BSTR* pVal).Holds.Get((int)EV_STG_API_ITEM_DETAIL. with the appropriate server name for each caller. Return value S_OK Success. Enterprise Vault dynamically generates the full URL as needed. DETAIL_LEVEL_HOLD_DATA). Examples [C++] . The URL returned includes the IIS virtual directory for the Enterprise Vault Web access application. HRESULT DeletionLevel([out.retval] EV_API_DELETION_LEVEL* pVal Current EV_API_DELETION_LEVEL value. [C#] item. Parameters [in] EV_API_DELETION_LEVEL newVal New EV_API_DELETION_LEVEL value. item->get_NativeItemURL(&bstr). users can recover a soft-deleted item.retval] EV_API_DELETION_LEVEL* pVal). The property is read/write. IItem :: DeletionLevel This property indicates the type of delete to be used for the archived item. item. See “EV_API_DELETION_LEVEL enumeration” on page 75. Syntax HRESULT DeletionLevel([in] EV_API_DELETION_LEVEL newVal). Items can be deleted completely (hard delete). item->put_Id(L"200501051649270000~0~9039eb282e3d4083b79f3298 dc8a1e60") item->put_ArchiveId(L"181E669473B52E64384C9A7D9EACA0E7E11100 00evsite"). [out. Remarks EV_API_DELETION_LEVEL is an enumerated value.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".NativeItemURL.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". or moved to the Enterprise Vault "dumpster" area (soft delete). . string url = item.Content Management API IItem :: DeletionLevel 185 CComBSTR bstr. The default value for this property is DELETION_LEVEL_SOFT_DELETE. For a period of time after deletion (configured by the administrator). Item. the administrator can enable the recovery of deleted items and specify how long soft-deleted items are to be kept. content.FileExtension = "msg". Version information ■ The ability to retrieve deleted items in Enterprise Vault is available from Enterprise Vault 2007.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". Example [in] item. DETAIL_LEVEL_ITEM_PROPERTIES).Insert(). item. content. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.Content. EV_API_DELETION_LEVEL evDL = item. Return value S_OK Success. .Title = "New title".DeletionLevel = EV_API_DELETION_LEVEL. [out] IItem item = cmAPI. item. content.msg". item. DELETION_LEVEL_SOFT_DELETE. The Item Undelete method can be used to recover a soft-deleted item.Get((int)EV_STG_API_ITEM_DETAIL. content. item.Data = "C:\\temp\\test. IContent content = item. item. in the Site Properties pages. or newVal is invalid.DeletionLevel.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite".OriginalLocation = "Inbox".186 Content Management API IItem :: DeletionLevel In the Enterprise Vault Administration Console. See “IItem3 :: Undelete” on page 210. Content Management API IItem :: CopyOptions IItem :: CopyOptions This property identifies the source item property values to be copied to the destination item. Remarks The calling application sets the CopyOptions property on the destination item object that is supplied in calls to the CopyTo or MoveTo methods. This value can be one or more of the enumerated values. then the values of the following ArchiveMetaData properties on the source item will be copied to the equivalent properties on the destination item. HRESULT CopyOptions([out. [out. The default value is ITEM_COPYOPTIONS_ARCHIVEMETADATA.retval] EV_STG_API_ITEM_COPYOPTIONS* pVal Current bit mask value. The value of CopyOptions can be one or more of the EV_STG_API_ITEM_COPYOPTIONS enumeration values. unless explicitly provided as part of the CopyTo or MoveTo method call: ■ SimpleIndexMetadata ■ ArchivedDate 187 .retval] EV_STG_API_ITEM_COPYOPTIONS* pVal). Syntax HRESULT CopyOptions([in] EV_STG_API_ITEM_COPYOPTIONS newVal). Use more than one by joining them with ‘OR’. If this is set. 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. The property is read/write. from the source item. then the caller would set the ArchivedDate property value on the destination item as the current date.188 Content Management API IItem :: CopyOptions ■ RetentionCategory ■ CurrentLocation ■ CurrentFolder ■ CustomIdentifier ■ CustomQualifier ■ CustomProperties See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 82. Any specified override value will take precedence over the CopyOptions property value setting. but the caller wants the ArchivedDate property on the destination item to be the current date and time (rather than copied from source). For example. item property values can be explicitly set on the destination item object in order to override the behavior of the CopyOptions property. . ITEM_COPYOPTIONS_ARCHIVEMETADATA. if the CopyOptions value is set to copy ArchiveMetaData properties. No Yes As above. Specifying item property override values Before calling CopyTo or MoveTo. Table 4-28 Effect of setting override item property values with ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value Item property Option selected Override value set Property value in on destination item copied item ArchivedDate Yes (Default) Yes Set to override value. Table 4-28 indicates the expected behaviour when setting override values for specific item properties with the CopyOptions enumeration value. Set to current date/time if the override value supplied as a null (VT_NULL) variant property value. ITEM_COPYOPTIONS_ARCHIVEMETADATA. Yes (Default) No Copied from source item. No No Set to zero value. No Yes As above. No Yes See “IArchiveMetaData2 :: CurrentLocation” on page 245. No Yes As above.Content Management API IItem :: CopyOptions Table 4-28 Item property Effect of setting override item property values with ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value (continued) Option selected Override value set Property value in on destination item copied item No No Set to current date/time. Yes Set to override value.3 189 . Yes Set to override value. Yes (Default) No Copied from source item. Yes (Default) No Copied from source item. RetentionCategory Yes (Default) Set to the site default Retention Category if override value specified as a zero length string value.2 CustomIdentifier Yes (Default) CustomQualifier CustomProperties CurrentLocation CurrentFolderId Set to zero value if override specified as zero value.1 No No Set to the site default Retention Category. Yes (Default) No Copied from source item. Yes (Default) Yes Set to override value. or the value set is not within enumeration. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.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. or an attempt has been made to set the CopyOptions of an existing item. when copying or moving items from one FSA or SharePoint archive to another.Where the source item is being copied or moved from a flat archive to a structured archive.190 Content Management API IItem :: CopyOptions Table 4-28 Item property Effect of setting override item property values with ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value (continued) Option selected Override value set Property value in on destination item copied item No No See “IArchiveMetaData2 :: CurrentLocation” on page 245. Dim ecmAPI Set ecmAPI = CreateObject("EnterpriseVault. 1. The property values should not be changed for such items. the source item's ArchiveMetaData values are preserved on the destination item.ContentManagementAPI") Dim oItem. Example In the following VBScript example. oDestItem . the CurrentLo-cation value on the destination item will be set to the value of OriginalLocation on the source item. 3. Return value S_OK Success. FSA and SharePoint Archiving use these custom properties to hold information for restoring items. If an override value is specified for the ArchivedDate property. The caller must have WRITE access permissions on the destination archive. Otherwise. Remarks It is important to make sure that this interface pointer has not been used before to perform an Insert or Get action. "{API} Can Use Extended API Features". This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles. the calling application must be in an Enterprise Vault role that includes the operation. Before calling Insert. an error will occur.Content Management API IItem :: Insert ‘ Establish the source item Set oItem = ecmAPI.CopyTo (oDestItem) IItem :: Insert This method is used to store an item in an archive. For structured archives.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. Syntax HRESULT Insert(void). the following properties must be populated: ■ IItem :: ArchiveId 191 . The Insert method stores an item in the specified archive.CopyOptions = 2 oItem. the caller must have write access to the destination archive folder.Item ‘ Establish the destination item Set oDestItem = ecmAPI.Item oDestItem. Enterprise Vault archives and indexes the item as a file.eml and a MIME format of message/rfc822. the Id property will be populated with the identifier of the item in the archive. which have a file extension of . . After this method has been called. Calling this method on an Item that already contains an Id (that is. If you assign any other values to an item. See Remarks above. and assuming the operation was successful. ■ CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. Enterprise Vault uses the supplied extension or MIME type to enhance indexing and storage functionality for content types such as Outlook messages.ms-outlook.msg and a MIME format of application/vnd. an item that has already been stored) will cause an error condition. the IItem :: Id property must be empty. ■ Both of IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set but they refer to different archive folders. and the target archive is a flat archive. ■ Either IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set.192 Content Management API IItem :: Insert ■ IContent :: Data ■ Either IContent :: FileExtension or IContent :: MIMEFormat. which have a file extension of . in which case this one must be destroyed and a new one created. When you call Insert. ■ SMTP messages. Enterprise Vault provides enhanced indexing and storage functionality for the following content types: ■ Outlook messages. ■ This item has previously been used. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One of the following situations exists: One of the required property values has not been set . Return value S_OK Success. spItem->get_Content(&pContent).Content Management API IItem :: Insert CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the insertion. "{API} Can Use Extended API Features". CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to insert items into a structured archive containing multiple root folders (for example.msg"). ■ The archive is in a read-only state. . CONTENTMANAGEMENTAPI_E_NO_ACCESS One of the following situations exists: 193 The caller does not have write access to the target archive or archive folder. a public folder archive). pContent->put_Title(L"new title"). Examples [C++] spItem. ■ ■ CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID An override value has been specified for ArchivedDate. IContent content = item. CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The target archive is full or exceeds its quota limit.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". IContent* pContent = null. Item Id is not unique in the target vault store. pContent->put_Data(L"C:\\temp\\test. spItem->Insert(). This error indicates that the caller should retry later.put->ArchiveId(L"181E669473B52E64384C9A7D9EACA0E7E1110000evs ite"). pContent->put_FileExtension(L"msg"). or Enterprise Vault is currently being backed up and is not accepting insert requests. 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. (The default Enterprise Vault Storage Administrator and Power Administrator roles include this operation).Content. [C#] item. but the caller is not in a role that includes the operation. The caller can "bitwise OR" the bit masks together.194 Content Management API IItem :: Get content. EV_STG_API_ITEM_DETAIL indicates the data to retrieve for an item. content. The item's CustomIdentifier and CustomQualifier properties can only be used when together they uniquely identify an item. Syntax HRESULT Get([in] LONG DetailLevel). When retrieving hold data only. Use more than one by joining them with ‘or’. IItem :: Get This method is used to retrieve an archived item or information about an item. the item's Id property must be used (DetailLevel = DETAIL_LEVEL_HOLD_DATA). . This value can be one or more of the EV_STG_API_ITEM_DETAIL enumerated values. content. item.Get(255) returns the item properties and the metadata. For example.Insert(). See “EV_STG_API_ITEM_DETAIL enumeration” on page 83. See “IIArchiveMetaData :: CustomIdentifier” on page 239. Parameters [in] LONG DetailLevel A bit-mask that specifies the item related data to retrieve.Data = "C:\\temp\\test.Title = "New title". 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. See “EV_STG_API_ITEM_DETAIL enumeration” on page 83. IItem.FileExtension = "msg". See also See “Content object” on page 212.msg". a content missing reason ("comr") property is returned with the reason. If the size of the item's converted content is larger than 5MB. or to an IStream or ILockbytes object that has been created ready to receive the item content. the "cont" property is included in the properties returned. Enable recovery of user deleted items. by selecting the archive setting. in Site properties. The soft delete functionality is enabled using the Enterprise Vault Administration Console. When DETAIL_LEVEL__SYSTEM_INDEXDATA is requested. then the converted content is not returned. Return values S_OK Success. items that have been soft deleted from the archive are retrieved. See “IContent :: Data” on page 220. This is the HTML representation (converted content) of the item or attachment. This limit can be changed using the registry setting: HKEY_LOCAL_MACHINE \Software \Wow6432Node \KVS \Enterprise Vault \MaxIndexDataHTMLContentKB This registry setting is described in the Registry Values guide. To retrieve the item content. vmrVALUENOTOBTAINED (2).Content Management API IItem :: Get If the soft delete feature has been enabled. 195 . Instead. the caller must populate the IContent::Data property with a file location on disk. The Content Management API supports IStream and ILockBytes implementations where the input data length provided by the Stat method is not known. any existing content will be overwritten. Note: If you specify a file. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the request. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. or the item's Archive Id and either its Id property. . This error indicates that the caller should retry later.196 Content Management API IItem :: Get CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer passed in is NULL. or CustomIdentifier and CustomQualifier properties. CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or has been deleted. 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. or the selected item is not present or has been deleted. have not been set. 0 SP4” on page 42. 0. NULL. and Enterprise Vault 6. item->Get(DETAIL_LEVEL_ITEM_CONTENT). and Enterprise Vault 6. STGM_READSWRITE | STGM_CREATE.0 SP2. IID_IStorage.0” on page 34.0 or later. See “Enterprise Vault 2007. Note that this feature requires MSXML 3. 197 . &pStream). item->get_Content(&pContent).0 SP4 and Enterprise Vault 7. pStorage->CreateStream(\xe3 Test Stream".0 SP2. ■ IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier require Enterprise Vault 8. and later. Enterprise Vault 7.0 SP2. See “Enterprise Vault 2007. STGFMT_FILE.0 SP4” on page 42. IStream* pStream = NULL. pContent->put_Data(pStream). Enterprise Vault 7. 0.Content Management API IItem :: Get Version information ■ Retrieving expanded distribution list information using the DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA value of EV_STG_API_ITEM_DETAIL enumeration is available in Enterprise Vault 6. See “Enterprise Vault 8. ■ When the enumerated value.0 SP4 and Enterprise Vault 7. IContent* pContent = NULL. NULL. This is fixed in Enterprise Vault 6. reinterpret_cast<void**>(&pStorage)). 0. Examples Refer to Microsoft documentation for details and usage of IStorage and IStream. STGM_READWRITE | STGM_CREATE. the correct date and time is now returned by IContent::ModifiedDate and IContent::CreatedDate. 0. StgCreateStorageEx(NULL. DETAIL_LEVEL_ITEM_CONTENT. is included as part of the input parameter for IItem::Get.0.0 SP2. IStorage* pStorage = NULL. [C++] item->put_Id( L" 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"). item->put_ArchiveId(L"181E669473B52E64384C9A7D9EACA0E7E1110000site" ). pContent = NULL. Item. item. //do something IItem :: Delete This method is used to delete an item from an archive.DETAIL_LEVEL_ITEM_CONTENT)).Data = "C:\\temp\\temp. item->Release(). pStorage = NULL. pStream = NULL.msg". content = item. The value of the DeletionLevel property will determine whether a hard or soft delete is performed. [C#] item. pStorage->Release(). . pContent->Release(). IContent content = null. the application programmer must have set the ArchiveId (to identify the archive containing the item).Get((int)(EV_STG_API_ITEM_DETAIL. item = NULL.Id = " 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".198 Content Management API IItem :: Delete //do something pStream->Release(). Remarks Calling the Delete method will remove the item from its archive. content. It cannot be called on an item whose ArchiveId and Id properties have not been set. as this will cause an error. and the Id property to identify the item within its container. Prior to calling this method.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite".Content. Syntax HRESULT Delete(void). the item's Retention Category does not permit deletion and the IArchiveMetadata OverrideOnHoldRetCat was not selected. This error indicates that the caller should retry later. CONTENTMANAGEMENTAPI_E_DELETION_BARRED The item cannot be deleted because deletions are not permitted. CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have delete access to the target archive or archive folder. item->putId(L"181E669473B52E64384C9A7D9EACA0E7E1110000evsite"). It is also possible that the server will reject the request because an item is "On Hold" or cannot be removed for compliance reasons. CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or has been deleted. or either the Archive Id or Item Id have not been set. Examples [C++] item->put_Archive_Id(L"181E669473B52E64384C9A7D9EACA0E7E1110000evsi te"). or the item is on legal hold. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the request. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed in.Content Management API IItem :: Delete The calling user must have the appropriate permissions to delete the item. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. Return value S_OK Success. 199 .or the archive is in a read-only state. ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Delete(). int canBeDeleted = (int)obj. [C#] IItem item = cmAPI.Get((int)EV_STG_API_ITEM_DETAIL. item.retval] VARIANT* CanDelete Pointer to a VARIANT containing the current value.200 Content Management API IItem :: CanBeDeleted item->Delete(). .CanBeDeleted. Syntax HRESULT CanBeDeleted([out. See “EV_STG_API_CAN_DELETE enumeration” on page 78. if (obj == 0) { item. Parameters [out.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". Remarks CanBeDeleted returns a value to indicate whether or not the item can be deleted. Return value S_OK Success.retval] VARIANT* CanDelete). item. object obj = item. item. DETAIL_LEVEL_ITEM_PROPERTIES).Item. } IItem :: CanBeDeleted This method determines if an item can be deleted from an archive. object obj = item. or either the Item IdorArchive Id has not been set.Content Management API IItem :: CopyTo CONTENTMANAGEMENTAPI_E_BAD_PARAMETER ANULL pointer has been passed in. CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have read access to the target archive or archive folder.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". or the selected item is not present or has been deleted. DETAIL_LEVEL_ITEM_PROPERTIES).Delete(). } IItem :: CopyTo This method is used to copy an item from one archive to another. This error indicates that the caller should retry later. item. item. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the request. Example IItem item = cmAPI.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Get((int)EV_STG_API_ITEM_DETAIL. if (obj == 0) { item.Item. int canBeDeleted = (int)obj. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. item. 201 .CanBeDeleted. CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or has been deleted. the calling application must be in an Enterprise Vault role that includes the operation. the calling application can set suitable override values on the destination item object. This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles. The CopyOptions property on the destination item object specifies the item elements to be copied across to the destination item. ■ Set the ArchiveId on the destination item object. ITEM_COPYOPTIONS_ARCHIVEMETADATA. the caller must have READ access to the source archive folder and WRITE access to the destination archive folder. Remarks The source and destination archive and vault store may be different. . if override values are not specified. ■ Set CopyOptions properties on the destination item object. From Enterprise Vault 8. is selected. For backwards compatibility.0. "{API} Can Use Extended API Features". otherwise an error will occur. Important considerations apply when specifying the destination archive folder. and WRITE access permissions on the destination archive. See “IItem :: CopyOptions” on page 187. This means that the default behaviour preserves the original ArchivedDate and OriginalLocation on the destination item. but the source and destination site must be the same. For structured archives. When copying an item: ■ Create the destination item object. the default action has changed.202 Content Management API IItem :: CopyTo Syntax HRESULT CopyTo([in] IItem* DestinationItem). The caller must have READ access to the source archive. Parameters [in] IItem* DestinationItem IItem interface pointer that represents the destination item. ■ Optionally set any ArchiveMetadata override property values if the copy option. If an override value is specified for the ArchivedDate property. the item content and its associated ArchiveMetaData and IndexData elements are copied from the source item. ■ Either IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set. This error indicates that the caller should retry later. or the selected retention category is not known or has been deleted. but they refer to different archive folders. or Enterprise Vault is currently being backed up and is not accepting copy requests. ■ The destination site is not the same as the source site. CONTENTMANAGEMENTAPI_E_NOT_FOUND The source or destination Archive Id is unknown or has been deleted. and the destination archive is a flat archive. or the source item cannot be found or has been deleted. ■ CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. 203 . CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the copy.Content Management API IItem :: CopyTo See “IArchiveMetaData2 :: CurrentLocation” on page 245. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One of the following situations exists: Either the destination archive or Item Id has not been set. ■ Both IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set. Return value S_OK Success. CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is full or exceeds its quota limit. pCmAPI->get_Item(&pItemSrc). ■ The target archive is in a read-only state. ■ An override value has been specified for ArchivedDate. a public folder archive). pItmDest->put_ArchiveId(CComBSTR(L"1E1FA1405F674644286ADBD247BA780C B1110000evsite")). ■ CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to copy items to a structured archive containing multiple root folders (for example. the Enterprise Vault Storage Administrator and Power Administrator roles include this operation). . IComplianceData* pDstComp = NULL. pItemSrc->CopyTo(pItemDst). pCmAPI->get_Item(&pItemDst). IItem* pItemDst = NULL. but the caller is not in a role that includes the operation. (By default. IArchiveMetaData* pDstAMD = NULL. pDstAMD->put_RetentionCategory(CComBSTR(L"Business")). pDstComp->SetBy(SETBY_RETCAT). pItemSrc->put_ArchiveId(CComBSTR(L"181E669473B52E64384C9A7D9EACA0E7 E1110000evsite")). pItemDst->get_ArchiveMetaData(&pDstAMD). Examples [C++] IItem* pItemSrc = NULL. pItemSrc->put_Id(CComBSTR(L"334880000000000~200707251102240000~0~D3 962A35951E4B03AE9CFB68AFE1218")). "{API} Can Use Extended API Features". pDstAMD->get_ComplianceData(&pDstComp).204 Content Management API IItem :: CopyTo CONTENTMANAGEMENTAPI_E_NO_ACCESS One of the following situations exists: No access to the archive or archive folder. SetBy = EV_STG_API_CP_SETBY. and WRITE access permissions on the destination archive and archive folder.ArchiveId = "1E1FA1405F674644286ADBD247BA780CB1110000ev site". 205 . itemSrc.ArchiveMetaData. itemSrc.Item.ComplianceData. otherwise an error will occur. itemSrc. Remarks The source and destination archive and vault store may be different. itemDst. the calling application must be in an Enterprise Vault role that includes the operation. itemDst. but the source and destination site must be the same.Item. itemDst.Content Management API IItem :: MoveTo [C#] IItem itemSrc = cmAPI.RetentionCategory = "Business".Id ="334880000000000~200707251102240000~0~D3962A35951E4B03 AE9CFB68AFE1218". The caller must have DELETE access to the source archive and archive folder. "Can Use Extended API Features". Parameters [in] IItem* DestinationItem Pointer to the destination item object.ArchiveId ="181E669473B52E64384C9A7D9EACA0E7E1110000ev site". IItem itemDst = cmAPI.ArchiveMetaData. If an override value is specified for the ArchivedDate property.SETBY_RETCAT.CopyTo(itemDst). IItem :: MoveTo This method is used to move an item from one archive to another. This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles. Syntax HRESULT MoveTo([in] IItem* DestinationItem). or the selected retention category is not known or has been deleted or the source item is not found or has been deleted. See “IItem :: CopyOptions” on page 187. See “IItem :: CopyTo” on page 201. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the copy. but it additionally removes the source item from the source archive after the copy has completed. ■ Either IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set and the destination archive is a flat archive. ■ Both IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set but they refer to different archive folders. ■ CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER One of the following situations exists: Either the destination archive or Item Id has not been set.206 Content Management API IItem :: MoveTo The MoveTo method is identical to the CopyTo operation. ■ The destination site is not the same as the source site. Return value S_OK Success. or Enterprise Vault is currently being backed up and is not accepting copy requests. The CopyOptions property on the destination item object specifies the item elements to be copied across to the destination item. 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. . but the caller is not in a role that includes the operation.Id ="334880000000000~200707251102240000~0~D3962A35951E4B03 AE9CFB68AFE1218". Example IItem itemSrc = cmAPI. or the item is on legal hold. ■ The caller does not have write access to the destination archive. a public folder archive). ■ CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to move items to a structured archive containing multiple root folders (for example. or archive folder. "{API} Can Use Extended API Features". or archive folder. the Enterprise Vault Storage Administrator and Power Administrator roles include this operation). CONTENTMANAGEMENTAPI_E_DELETION_BARRED The source item cannot be deleted because deletions are not permitted for the archive. 207 .Item. IItem itemDst = cmAPI. the item's Retention Category does not permit deletion and the IArchiveMetadata OverrideOnHoldRetCat was not selected.Content Management API IItem :: MoveTo CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is full or exceeds its quota limit.ArchiveId ="181E669473B52E64384C9A7D9EACA0E7E1110000ev site". itemDst. (By default. CONTENTMANAGEMENTAPI_E_NO_ACCESS One of the following situations exists: The caller does not have delete access to the source archive. itemSrc.ArchiveId = "1E1FA1405F674644286ADBD247BA780CB1110000ev site".Item. ■ An override value has been specified for ArchivedDate. itemSrc. ■ The source or destination archive is in a read-only state. The default value (NULL) is returned.MoveTo(itemDst).retval] EV_STG_API_DELETION_REASON* pVal) Parameters [out. . See “EV_STG_API_DELETION_REASON enumeration” on page 80. IItem2 :: DeletionReason If an item no longer exists in the archive.208 Content Management API IItem2 :: DeletionReason itemDst.SetBy = EV_STG_API_CP_SETBY. Item::Id and Item::ArchiveId properties must be specified on the Item object. Syntax HRESULT DeletionReason([out.ArchiveMetaData.SETBY_RETCAT. Return value S_OK Success. itemDst. The property is populated only when it is accessed. To retrieve the DeletionReason property. This property is read only. then the DeletionReason property can be used to determine if the item has been deleted. S_FALSE Success.ComplianceData. Remarks If an attempt to retrieve an item fails because the item cannot be found. itemSrc.retval] EV_STG_API_DELETION_3REASON* pVal Current EV_STG_API _DELETION_REASON value.RetentionCategory = "Business".ArchiveMetaData. EV_STG_API_DELETION_REASON is an enumeration value that identifies why the item was deleted. this property can be used to find out why the item was deleted. destItem. if (e.DETAIL_LEVEL_ARCHIVE_METADATA |EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES |EV_STG_API_ITEM_DETAIL. try { // Try to get the item destItem. CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have read access to the archive.ErrorCode == (int)EV_STG_API_ErrorCodes. // check the deletion reason of the item.DETAIL_LEVEL_SYSTEM_INDEXDATA)). or the item's Archive Id or Id property have not been set. 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. CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND) { EV_STG_API_DELETION_REASON delReason = EV_STG_API_DELETION_REASON. try 209 . } catch (COMException e) { // If ITEM NOT FOUND error is thrown. Example [C#] Item2 destItem = (IItem2)cmAPI.com".Id = "200908040000000~200908041247260000~Z~80BD742AD7B88D0 850524974B9F44901".DELETION_REASON_UNKNOWN.Get((int)( EV_STG_API_ITEM_DETAIL.corp.Item. destItem.Content Management API IItem2 :: DeletionReason CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is NULL.ArchiveId = ="1BFE65542AFD18F418824B15EF3288CD51110000 EVServer. delReason). Return value S_OK Success.210 Content Management API IItem3 :: Undelete { delReason = destItem.DeletionReason. } } } IItem3 :: Undelete If an item has been moved to the Enterprise Vault "dumpster" area (soft deleted). The item is restored from the dumpster area to the archive. both the Archive ID and the Item ID must be set on the Item object. Remarks The caller must be in an Enterprise Vault role that allows the operation "Can undelete items in any archive". . "Placeholder Application". (The task definition. } finally { // Log that the item was not found together with the // deletion reason LogItemNotFound(destItem. is included in the role. retval] VARIANT_BOOL* pVal) Parameters [out.) Before calling Undelete. this method can be used to recover the item.retval] VARIANT_BOOL* pVal A value of TRUE indicates that the item has been recovered. "EVT Execute undelete from archives". Syntax HRESULT Undelete([out. CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id has not been found. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. "Can undelete items in any archive". item. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resources to complete the request.Item. CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have undelete access to the archive. or has been removed from the Enterprise Vault dumpster area. This error indicates that the caller should retry later. CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND The item could not be found in the archive. Version information ■ IItem3 interface requires Enterprise Vault 9. Examples [C#] IItem3 item = (IItem3)cmAPI.0. the caller is not in a role that allows the operation. or the item's Archive Id or Item Id property have not been set. See also ■ See “IItem :: DeletionLevel” on page 185.ArchiveId = 211 . That is.Content Management API IItem3 :: Undelete CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is NULL. oItem3 Set ecmAPI = CreateObject("EnterpriseVault.Undelete if (Err. item. . oItem. [VBScript] Dim ecmAPI.com" oItem3.ID = "201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51651" dim results result = oItem3.example.Echo "Item Undeleted" else WScript.Echo "Error: " & Err.Id = "201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51 651".com".number <> 0) then WScript.ArchiveId = "118F819534E391C43B6854E2DD3A708C61110000EV.Description end if if result then WScript.IDispatchQueryInterface(oItem. bool UnDeleted = item.212 Content Management API Content object "118F819534E391C43B6854E2DD3A708C61110000EV."{E5C7F710-36AD-4e24-B00A-E3D7 09FF76CD}") oItem3.Undelete().example.Echo "Item has not been Undeleted" end if 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.ContentManagementAPI") set oItem = ecmAPI.Item set oItem3 = ecmAPI. or an IStream or ILockBytes object containing the content to be archived. OriginalLocation The original location of the item. content.Data = "C:\\temp\\test.FileExtension = "msg". Data The Data property is used to pass the raw content of the item to or from the archive.Insert().Content Management API Content object Syntax interface IContent : IDispatch Member summary Table 4-29 IContent Properties Property Description Title The name.Title = "New title". MIMEFormat Optional property describing the MIME file format of the item. content. Example item. The author of the item. OriginalSize This property contains the size in bytes of the original item that was archived. content. The parameter can be the path to a file that contains the content to be archived. 213 .ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". item. Author Optional property. CreatedDate Optional property that contains the UTC date and time that the item was created.msg". title or subject of the item.OriginalLocation = "Inbox". content. IContent content = item. ModifiedDate Optional property that contains the UTC date and time that the item was last modified. Folder hierarchy is represented using back slashes as separators. FileExtension File extension describing the format of the item.Content. Title. title or subject of the item. Return value S_OK Success. Parameters [out. an error will occur. [in] BSTR newVal The new title of this item.214 Content Management API IContent :: Title IContent :: Title This property holds the name. . The property is read/write. Syntax HRESULT Title([out.Content. HRESULT Title([in] BSTR newVal). or the title of this item has already been set in a previous call to Insert. Example [C#] IContent content = itm. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. string title = content. IContent :: OriginalLocation This property holds the original location of the item. retval] BSTR* pVal The title of this item. Remarks If an attempt is made to change the title after a call to Insert or Get. retval] BSTR* pVal). content.FileExtension = "msg". Example item. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. content. HRESULT OriginalLocation([in] BSTR newVal). The default value (NULL) is returned.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". or this property has already been set. Syntax HRESULT OriginalLocation([out.Content. S_FALSE Success. content.msg". The property is read/write. Parameters [out.Insert().Title = "New title". IContent :: FileExtension This property holds the file extension describing the format of the item. 215 .OriginalLocation = "Inbox". item. Return value S_OK Success. retval] BSTR* pVal Pointer to a BSTR that will contain the original location [in] BSTR newVal The original location value to be set.Content Management API IContent :: FileExtension The property is read/write.Data = "C:\\temp\\test. content. IContent content = item. retval] BSTR* pVal). and opened correctly by a web browser using IItem :: BrowserViewURL. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. content.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". The preceding period in a file extension can be included or omitted when setting a value.Title = "New title". HRESULT FileExtension([in] BSTR newVal).msg’ where the content is in Outlook message file format. content. Parameters [out.FileExtension = "msg". . It is required so that the item can be indexed when it is archived.txt’ where the content is simple text. content. It will be added by the API when the item is archived.bin". Remarks This property describes the format of the item. For example. [in] BSTR newVal The file extension to use.216 Content Management API IContent :: FileExtension Syntax HRESULT FileExtension([out.Content. use ‘ . IContent content = item. or an attempt has been made to change an existing value. retval] BSTR* pVal Pointer to a BSTR that will contain the current file extension. Return value S_OK Success. retval] BSTR* pVal). Once this value has been set it cannot be changed. The default value is ". Example item. or ‘.OriginalLocation = "Inbox". 217 . or an attempt has been made to change the value of this property after the item has been archived. This property is useful for HTTP Web-based client applications that process byte streams with the MIME type parameter (content-type). or ‘application/vnd. rather than files. Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. item. Parameters [out.ms-outlook’ where the content is in Outlook message file format. If the property is set. IContent :: MIMEFormat This property is optional and describes the MIME file format of the item. Syntax HRESULT MIMEFormat([out.msg".Insert().Content Management API IContent :: MIMEFormat content. it cannot be changed after the item has been archived. use ‘text/plain’ where the content is simple text. HRESULT MIMEFormat([in] BSTR newVal). 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.Data = "C:\\temp\\test. retval] BSTR* pVal). The property is read/write. IContent content = item. . retval] VARIANT* pVal Pointer to a VARIANT that will contain the value of the property.Title = "New title".Content. content. content. HRESULT CreatedDate([in] VARIANT newVal). item. content.Insert(). IContent :: CreatedDate This property contains the UTC date and time that the item was created. content.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". Parameters [out. Remarks Once this item has been archived it is not possible to change the value of this property. The property is read/write. retval] VARIANT* pVal). Return value S_OK Success.OriginalLocation = "C:\\temp". [in] VARIANT newVal The new value to set this property.218 Content Management API IContent :: CreatedDate Example item.Data = "C:\\temp\\test.MIMEFormat = "text/plain".txt". Syntax HRESULT CreatedDate([out. Content. or the data passed in is corrupt and of the wrong data type.Item. 219 . item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". Parameters [out. IContent cont = item. DETAIL_LEVEL_ITEM_PROPERTIES). object obj = content. item. item. retval] VARIANT* pVal).Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". DateTime dt = (DateTime)obj. or either an attempt to modify the property value after the item has been archived has been made. [in] VARIANT newVal Optional property that contains the UTC date and time that the item was last modified. Syntax HRESULT ModifiedDate([out.Get((int)EV_STG_API_ITEM_DETAIL. The property is read/write. retval] VARIANT* pVal The UTC date and time that the item was last modified. HRESULT ModifiedDate([in] VARIANT newVal). IContent :: ModifiedDate This property contains the UTC date and time that the item was last modified. Example IItem item = cmAPI.CreatedTime.Content Management API IContent :: ModifiedDate CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. DETAIL_LEVEL_ITEM_PROPERTIES). item. The property is read/write. IContent cont = item. Return value S_OK Success. .Content.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Get((int)EV_STG_API_ITEM_DETAIL. IContent :: Data This property is used to pass the raw content of the item to or from the archive. or either this property is being modified after the item has been saved in the archive.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Item. item. Syntax HRESULT Data([out. DateTime dt = (DateTime)obj. Example IItem item = cmAPI. retval] VARIANT* pVal). object obj = content. item. HRESULT Data([in] VARIANT newVal). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.ModifiedTime.220 Content Management API IContent :: Data Remarks Once this item has been archived it is not possible to change the value of this property. or the value passed into the property is not in the correct format. properties and archive metadata is not archived until the Insert method has been called. or an IStream or ILockBytes object.Runtime. . EOAC_NONE.InteropServices.InteropServices.Stream. -1.NET application.ComTypes. you will need to create a managed implementation of the System. This property must be set to the path of a file on disk.IStream and implements its methods using an instance of a managed stream.IStream interface.Runtime. ■ All use of the Content Management API is from threads set to use the COM single-threaded apartment.IO. When using a version of the Enterprise Vault API runtime prior to Enterprise Vault 8.ComTypes. any existing content will be overwritten when retrieving an item. [in] VARIANT newVal Variant containing the data. Remarks One important point to remember is that the item data. is not set to use the COM single-threaded apartment (STA) model. and the overhead of saving the item content to a file is not acceptable. System.0. For example. If the calling application is a . .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.NET class that inherits from System. with the following parameter values: CoInitializeSecurity(NULL. Note: If you specify a file. retval] VARIANT* pVal Pointer to a VARIANT that will contain the actual item data. The Content Management API supports IStream and ILockBytes implementations where the input data length provided by the Stat method is not known. invokes CoInitializeSecurity via PInvoke. RPC_C_IMP_LEVEL_IDENTIFY. RPC_C_AUTHN_LEVEL_CALL. ■ The application's entry point.Content Management API IContent :: Data 221 Parameters [out. the Main method. NULL). the Main method. NULL. NULL. you can create a . NULL. the Content Management API is not invoked from the application's entry point method. such as Windows Forms applications. content. A C# implementation of IStream can be used instead: MemoryStream itemCont = new MemoryStream(). IContent :: OriginalSize This property returns the size of the original item. or any other executable where COM security has already been initialized to restrict remote access. Syntax HRESULT OriginalSize([out.msg". before it was archived. .Content. The property is read only. content. or an attempt has been made to modify this property after the item has been stored in the archive.222 Content Management API IContent :: OriginalSize Applications where these conditions cannot be met.Data = (IStream) new ComStreamAdaptor(itemCont).Data = "C:\\temp\\temp. in bytes. retval] VARIANT* pVal). cannot support insert or retrieval of items larger than 4MB. Return value S_OK Success. Example [C#] IContent content = itm. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. applications hosted by IIS. The VARIANT should have been set to VARTYPE vt = VT_R8 Remarks This property is only available after an item has been archived. Example IItem item = cmAPI. Syntax HRESULT Author([out. item.Get((int)EV_STG_API_ITEM_DETAIL. double size = (double)obj. No error will be returned if this property is called before archiving and the returned value will be 0.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". HRESULT Author([in] BSTR newVal).ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". item. The property is read/write and optional. retval] VARIANT* pVal Pointer to a VARIANT that will contain the value of this property. 223 . CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. IContent cont = item. object obj = content. item.Content.OriginalSize. retval] BSTR* pVal).Content Management API IContent :: Author Parameters [out. Return value S_OK Success. IContent :: Author This property contains the author of the item. DETAIL_LEVEL_ITEM_PROPERTIES).Item. Author = "Charles Dickens" content. item.Item. once set and the item archived. However. Return value S_OK Success. content. IContent content = item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". an error will occur if an attempt is made to change the value. . content. or an attempt has been made to change the value of this property after the item has been archived.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000EVSite". Example [C#] [in] item.Content. content. item. content. retval] BSTR* pVal Pointer to a BSTR that will contain the current value of this property.OriginalLocation = "Inbox".224 Content Management API IContent :: Author Parameters [out. [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. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. [out] IItem item = cmAPI. item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Insert().FileExtension = "msg".Data = "C:\\temp\\test.Title = "New title".msg". DETAIL_LEVEL_ITEM_PROPERTIES). string author = content.Content Management API ArchiveMetaData object item. IContent cont = item. 225 . the Index Sequence Number (ISN) of an item and a read/write version of the ArchivedDate property. IArchiveMetaData2 provides additional properties for determining the location of an item.Get((int)EV_STG_API_ITEM_DETAIL." for example.Content. 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. 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.Author. 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. and provides calling applications with a set of properties that describe how the Item is archived. Typical category is "Business. ISimpleIndexMetadata methods and properties enable the calling application to retrieve the index properties of an archived item. RetentionExpires Read only This property that contains the UTC date and time that the item will be able to be deleted from the archive. SavesetSize Read only This property contains the saveset size (that is. IndexData Read only Pointer to a SimpleIndexMetadata object. IsItemSecured Read only Property that indicates that is it safe to delete the original item from the source store. then the item may not be restored as part of a disaster recovery of the Enterprise Vault server. 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. or add custom index properties to an item as it is archived.226 Content Management API ArchiveMetaData object Table 4-30 IArchiveMetaData properties (continued) Property Read/Write Description OverrideOnHoldRetCat Read/Write This property is set TRUE to delete an item that Enterprise Vault will normally prevent because the Retention Category On-hold flag is enabled. CustomIdentifier Read/write This property. together with CustomQualifier can be used to provide proprietary identity information for the item. the final size of the archived item as stored on disk) rounded to the nearest KB. ArchivedDate Read only This property contains the UTC date and time that the item was originally stored into the archive. If the original item is deleted before the archive item is secured. The Search API can be used to find items with specific index data. . Remarks Version information IArchiveMetaData2 interface requires Enterprise Vault 8. ArchivedDate Read/write The UTC date and time that the item was originally stored in the archive. SequenceNum Read only The Index Sequence Number (ISN) of the archived item. The property is only intended for use with structured archives. 227 . The property is only intended for use with structured archives. together with CustomIdentifier can be used to provide proprietary identity information for the item. Table 4-32 IArchiveMetaData2 properties Property Read/Write Description CurrentLocation Read/write Specifies the archive folder path to the current location of the item in the archive. CustomProperties Read/write This property can be used to hold proprietary information about the stored item.0. CurrentFolderId Read/write The ID of the current archive folder for the item.Content Management API ArchiveMetaData object Table 4-30 IArchiveMetaData properties (continued) Property Read/Write Description CustomQualifier Read/write This property. Table 4-31 IArchiveMetaData method Method Description Update Used to apply ComplianceData changes to a stored item. Currently it is not possible to modify this property using the Content Management API after the item has been archived. Remarks An example of this would be "Business" or any other retention category created using the Enterprise Vault Administrator Console.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". DETAIL_LEVEL_ARCHIVE_METADATA). See “About Retention API” on page 562. item.Item.228 Content Management API IArchiveMetaData :: RetentionCategory Example IItem item = cmAPI.Get((int)EV_STG_API_ITEM_DETAIL. retval] BSTR* pVal Pointer to a BSTR containing the current value of this property.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". The retention category Id may be specified as an alternative. [in] BSTR newVal New value to set this property to. Parameters [out. HRESULT RetentionCategory([in] BSTR newVal). Syntax HRESULT RetentionCategory([out. The property is read/write.ArchiveMetaData. . item. item. The Retention API can be used to discover or create retention categories. IArchiveMetaData amd = item. retval] BSTR* pVal). IArchiveMetaData :: RetentionCategory This property contains the name or Id of the retention category assigned to the item. item.Content Management API IArchiveMetaData :: ComplianceDevice Return value S_OK Success. The request should be retried later.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". S_FALSE Success. The default value (NULL) is returned. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory Service is not running. IArchiveMetaData :: ComplianceDevice This property indicates whether the item is stored on a compliance device on which retention periods can be set. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. IArchiveMetaData amd = item.RetentionCategory. string retCat = amd.ArchiveMetaData.Item. Example IItem item = cmAPI. DETAIL_LEVEL_ARCHIVE_METADATA).Get((int)EV_STG_API_ITEM_DETAIL. item. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". Syntax HRESULT ComplianceDevice([out. retval] VARIANT_BOOL* pVal). The property is read only. item. 229 . Return value S_OK Success.230 Content Management API IArchiveMetaData :: OverrideOnHoldRetCat Parameters [out. item. if (conpDevice == true) { //do something IArchiveMetaData :: OverrideOnHoldRetCat This property enables deletion of an item even if the retention category on-hold flag is enabled. Syntax HRESULT OverrideOnHoldRetCat([out. retval] VARIANT_BOOL* pVal). DETAIL_LEVEL_ARCHIVE_METADATA).Item. The property is read/write. 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. HRESULT OverrideOnHoldRetCat([in] VARIANT_BOOL newVal).ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". bool compDevice = amd. item. . item. Example IItem item = cmAPI.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ComplianceDevice. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. IArchiveMetaData amd = item.Get((int)EV_STG_API_ITEM_DETAIL.ArchiveMetaData. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Content Management API IArchiveMetaData :: OverrideOnHoldRetCat Parameters [out.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000EVSite".Title = "New title".msg". item. Once an item has been archived this property cannot be changed. 231 .FileExtension = "msg". amd. content. item.Content.ArchiveMetaData. [out] IItem item = cmAPI. IArchiveMetaData amd = item.Item. Return value S_OK Success.Data = "C:\\temp\\test. or an attempt was made to modify this property after the item had been stored in an archive. content. Example [in] item.Insert(). item.OverrideOnHoldRetCat = true. IContent content = item. content.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". content. 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.OriginalLocation = "Inbox". See “IArchiveMetaData2 :: ArchivedDate” on page 255. . if (override == true) { //do something IArchiveMetaData :: ArchivedDate This property contains the UTC date and time that the item was originally stored in the archive.232 Content Management API IArchiveMetaData :: ArchivedDate item. DETAIL_LEVEL_ARCHIVE_METADATA). IArchiveMetaData amd = item.ArchiveMetaData.Get((int)EV_STG_API_ITEM_DETAIL.0. Version information At Enterprise Vault 8. The property is read only. bool override = amd. OverrideOnHoldRetCat. retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived date of this item Remarks This property is optional. Parameters [out. Syntax HRESULT ArchivedDate([out. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. retval] VARIANT* pVal). Return value S_OK Success. this property becomes a read/write property. or the value input is not a valid date time. ArchiveMetaData.ArchivedDate. Parameters [out.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Content Management API IArchiveMetaData :: ComplianceData Example IItem item = cmAPI. Syntax HRESULT ComplianceData([out. The IComplianceData interface enables compliance metadata to be set on an item in an archive. DETAIL_LEVEL_ARCHIVE_METADATA). See “ComplianceData object” on page 281. retval] IComplianceData** pVal). IArchiveMetaData amd = item. 233 . retval] IComplianceData** pVal Pointer to a valid IComplianceData pointer. Return value S_OK Success.Item. item. Remarks Although this property itself is read-only. The property is read only. object obj = amd. its own properties allow compliance data to be added/modified.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Get((int)EV_STG_API_ITEM_DETAIL. item. item. 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. DateTime dt = (DateTime) obj. retval] VARIANT* pVal). The VARIANT type of this property should be vt = VT_UI4.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". EV_STG_API_CP_UNITS evUnits = compData. DETAIL_LEVEL_ARCHIVE_METADATA).Item. object obj = compData. IArchiveMetaData amd = item. Syntax HRESULT SavesetSize([out. item. Example IItem item = cmAPI. rounded to the nearest KB.Value. ulong val = (ulong)obj. this property cannot be modified on an item that has already been archived.Get((int)EV_STG_API_ITEM_DETAIL.234 Content Management API IArchiveMetaData :: SavesetSize CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. .ComplianceData. The property is read/write. Although it is marked as read/write. item. Parameters [out. item.ArchiveMetaData. IArchiveMetaData :: SavesetSize This property holds the size of the archived item saveset. 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. IComplianceData compData = amd.Units. Example IItem item = cmAPI.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". is set on the item Get method. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. item. Parameters [out. DETAIL_LEVEL_COMPLIANCE_DATA. Syntax HRESULT RetentionExpires([out.ArchiveMetaData. ulong size = (ulong)obj.SavesetSize.retval] VARIANT* pVal).Item.Get((int)EV_STG_API_ITEM_DETAIL.Content Management API IArchiveMetaData :: RetentionExpires Return value S_OK Success. item. 235 . object obj = amd. The property is read only. IArchiveMetaData amd = item. Remarks This property value is populated when the item detail level.retval] VARIANT* pVal Pointer to a VARIANT that will contain the current value. IArchiveMetaData :: RetentionExpires This property contains the UTC date and time when the item can be deleted from a compliance storage device. or an attempt has been made to modify this property after it has been stored in an archive. DETAIL_LEVEL_ARCHIVE_METADATA).Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". item. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. DETAIL_LEVEL_COMPLIANCE_DATA))). item.236 Content Management API IArchiveMetaData :: IndexData See “EV_STG_API_ITEM_DETAIL enumeration” on page 83.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". IArchiveMetaData :: IndexData This property returns a pointer to a SimpleIndexMetadata object. Example IItem item = cmAPI.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". object obj = amd. The property is read only. IArchiveMetaData amd = item. If the item is stored on a compliance device. retval] ISimpleIndexMetadata** pVal). which is equivalent to an Automation date of 0.Item. item.ArchiveMetaData. DateTime dt = (DateTime)obj. then then the property value is 30/12/1899 00:00:00. Syntax HRESULT IndexData([out. then the property value is the UTC date and time when the item can be deleted from the device. and add custom index properties when the item is archived. item. If the storage device is not a compliance device. which allows the calling application to enumerate system and custom index properties for the current item.Get((int)((EV_STG_API_ITEM_DETAIL. . The VARTYPE of the variant should be vt = VT_DATE. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.RetentionExpires. Return value S_OK Success. 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.EnterpriseVault.ArchiveMetaData. The Search API can be used to find items with specific index properties and values. ■ See “SimpleIndexMetadata object” on page 256. retval] ISimpleIndexMetadata** pVal Pointer to a SimpleIndexMetadata object. Example IArchiveMetaData amd = item. Requirements Requires KVS. or an attempt has been made to access this property after the item has been archived. 237 . ISimpleIndexMetadata simple = amd. See “Adding custom index metadata” on page 72. IArchiveMetaData :: IsItemSecured This property indicates that is it safe to delete the original item from the source store.Common.Content Management API IArchiveMetaData :: IsItemSecured Parameters [out. Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. The additional index data is then available in the archive's index.IndexData.dll. See also ■ See “IItem :: Get” on page 194. Return value S_OK Success. Parameters [out. it may mean that the item has been backed-up. The meaning of "secured" depends upon the storage device. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. if (isSecured == true) { //safe to delete original item from the source .Get((int)(EV_STG_API_ITEM_DETAIL.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". 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.238 Content Management API IArchiveMetaData :: IsItemSecured The property is read only. retval] VARIANT_BOOL* pVal).Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ArchiveMetaData.IsItemSecured.Item. Example IItem item = cmAPI. then the item may not be restored as part of a disaster recovery of the Enterprise Vault server. or that the storage device has replicated the item to a duplicate device. item. DETAIL_LEVEL_ARCHIVE_METADATA) IArchiveMetaData amd = item. Syntax HRESULT IsItemSecured([out. item. bool isSecured = amd. item. The property is read/write. 239 . The default value (NULL) is returned. This property is used in conjunction with the CustomQualifier property. application GUID. HRESULT CustomIdentifier ([out.Content Management API IIArchiveMetaData :: CustomIdentifier IIArchiveMetaData :: CustomIdentifier This property. Return value S_OK Success. For example. as a prefix to the application identifier. It is possible to duplicate values using the CustomIdentifier/CustomQualifier properties. To ensure uniqueness. As FSA and SharePoint Archiving use this property to hold information for restoring items. [out. the property value should not be changed for items archived using FSA or SharePoint Archiving. For example. retval] BSTR* pVal).application Id. for example a GUID. the CustomIdentifier value should use an application namespace. which defaults to zero. Parameters [in] BSTR newVal New value to set for this property. Syntax HRESULT CustomIdentifier ([in] BSTR newVal). retval] BSTR* pVal Pointer to a BSTR containing the current value of this property. together with the CustomQualifier property. can be used to provide proprietary identity information for the item. S_FALSE Success. this property could be used to hold the source store's identifier for the original item. Remarks The maximum length of this property is 255 characters. ArchiveMetaData.0’?><properties><key = ‘1’ value=‘some value’/></properties>" const CUSTOM_ID = "AcmeWidgetId-00002" const CUSTOM_QUALIFIER = 1 Dim oItem oItem. const CUSTOM_PROPERTIES = "<?xml version=‘1.ArchiveMetaData.240 Content Management API IIArchiveMetaData :: CustomQualifier CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. For example. together with the CustomIdentifier property. or the value exceeds 255 characters. can be used to provide proprietary identity information for the item. this property could hold the document version information. . Example This VBScript example shows how CustomIdentifier. CustomQualifier and CustomProperties can be set. retval] LONG* pVal).CustomProperties = CUSTOM_PROPERTIES oItem.ArchiveMetaData. or either an attempt has been made to modify this property after it has been stored in an archive. Syntax HRESULT CustomQualifier ([in] LONG newVal). HRESULT CustomQualifier ([out.CustomIdentifier = CUSTOM_ID oItem. if different versions of a document are archived. The property is read/write. Parameters [in] LONG newVal New value to set for this property.CustomQualifier = CUSTOM_QUALIFIER IIArchiveMetaData :: CustomQualifier This property. The property can only be set after the CustomIdentifier property has been set.ArchiveMetaData. CustomQualifier and CustomProperties can be set.CustomProperties = CUSTOM_PROPERTIES oItem. Return value S_OK Success S_FALSE Success.CustomQualifier = CUSTOM_QUALIFIER 241 .ArchiveMetaData. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. Example This VBScript example shows how CustomIdentifier.0’?><properties><key = ‘1’ value=‘some value’/></properties>" const CUSTOM_ID = "AcmeWidgetId-00002" const CUSTOM_QUALIFIER = 1 Dim oItem oItem. const CUSTOM_PROPERTIES = "<?xml version=‘1. Remarks This property is used in conjunction with the CustomIdentifier property. retval] LONG* pVal Pointer to a LONG containing the current value of this property. The default value (0) is returned. If a CustomIdentifier has been set this property defaults to zero.CustomIdentifier = CUSTOM_ID oItem. or either an attempt has been made to modify this property after it has been stored in an archive.Content Management API IIArchiveMetaData :: CustomQualifier [out. 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.ArchiveMetaData. or the CustomIdentifier property has not been set. The default value (NULL) is returned. or the value exceeds 2500 characters. Syntax HRESULT CustomProperties ([in] BSTR newVal). retval] BSTR* pVal). the property value should not be changed for items archived using FSA or SharePoint Archiving. Parameters [in] BSTR newVal New value to set for this property. HRESULT CustomProperties ([out. Remarks The maximum length of this property is 2500 characters. . The property is read/write. Return value S_OK Success S_FALSE Success. [out. CustomQualifier and CustomProperties can be set.242 Content Management API IIArchiveMetaData :: CustomProperties IIArchiveMetaData :: CustomProperties This property can be used to hold proprietary information about the stored item. Example This VBScript example shows how CustomIdentifier. retval] BSTR* pVal Pointer to a BSTR containing the current value of this property. As FSA and SharePoint Archiving use this property to hold information for restoring items. or either an attempt has been made to modify this property after it has been stored in an archive. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. ■ You cannot remove the compliance period completely by setting values to "NONE". you cannot assign a different retention category.ArchiveMetaData. ■ The new retention period must be longer than the original retention period. Currently the Update method cannot be used to update any other archive metadata properties. Syntax HRESULT Update(void) Remarks The ArchiveId and Id properties must be set prior to calling the Update method.ArchiveMetaData. ■ The only values that can be changed currently are the compliance unit and value properties. If this is not the case. 243 .CustomProperties = CUSTOM_PROPERTIES 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. 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.Content Management API IArchiveMetaData :: Update const CUSTOM_PROPERTIES = "<?xml version=‘1. a bad HRESULT will be returned.0’?><properties><key = ‘1’ cost=‘543’/></properties>" const CUSTOM_ID = "AcmeWidgetId-00002" const CUSTOM_QUALIFIER = 1 Dim oItem oItem.CustomIdentifier = CUSTOM_ID oItem.CustomQualifier = CUSTOM_QUALIFIER oItem. ■ You can only extend the retention period of the retention category assigned to the item.ArchiveMetaData. The operation will only be performed if the compliance device allows it. indicating the cause of the failure. See “ComplianceData object” on page 281. IArchiveMetaData amd = item. Example IItem item = cmAPI.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". This error indicates that the caller should retry later. CONTENTMANAGEMENTAPI_E_INVALID_DEVICE The storage device is not a compliance device.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Get((int)((EV_STG_API_ITEM_DETAIL. item. item. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the update request. item. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed in. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.244 Content Management API IArchiveMetaData :: Update Return value S_OK Success. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. or either the archive or item Id has not been set. . or an attempt has been made to change it.Item. CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have write access to the target archive or archive folder. DETAIL_LEVEL_COMPLIANCE_DATA))). or there is an error with the retention category. or Enterprise Vault is currently being backed up and is not accepting update requests.ArchiveMetaData. Parameters [in] BSTR newVal Folder path to be set as the item's current location in the archive. that is. This property is only intended for use with structured archives. retval] BSTR* pVal). copy or move item operations. archive folder. retval] BSTR* pVal Archive folder path set as the item's current location. HRESULT CurrentLocation ([out. Remarks The Items collection object can be used to populate this property automatically.Units = EV_STG_API_CP. The property is read/write. compData. 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. 245 . compData. or is to be stored when performing insert. Syntax HRESULT CurrentLocation ([in] BSTR newVal). amd. CP_UNITS_MONTHS. IArchiveMetaData2 :: CurrentLocation This property specifies the path of the archive folder in which the item is currently stored. The following examples illustrate the default root archive folder path used by the CurrentLocation property for the different types of archives: ■ Mailbox archives.Value = 18. archives that contain folders.ComplianceData.Content Management API IArchiveMetaData2 :: CurrentLocation IComplianceData compData = amd. [out.Update(). then the item is located in the folder "FolderA". if the folder path for an Exchange Public Folder archiving target is "EXCHSVR\Sales\Documents". if the folder path for an FSA volume archiving target is "\\FileSVR1. ■ FSA archives. then the item is located in the folder "UK". and the value of the CurrentLocation property is "EXCHSVR\Sales\Documents\FolderA". ■ SharePoint archives. and the value of the CurrentLocation property is "http://sharepoint/sites/marketing/UK". ■ The backslash character (‘\’) is treated as the folder path subfolder separator character. if the URL for a SharePoint site collection archiving target is "http://sharepoint/sites/marketing". which is subfolder of the root archive folder for the Public Folder archiving target. The following syntax rules apply when retrieving or setting the CurrentLocation property value for archives other than SharePoint archives.Example. Note that the syntax rules applied to SharePoint archive folder paths differ from those applied to folder paths in other types of archive.Example.COM\FSA Volume\5\NewFolder". For example. The example value "Inbox\Accounts" represents the location of an item in the folder "Accounts".COM\FSA Volume\5". The default root archive folder path in the CurrentLocation property value represents the location of the Exchange Public Folder archiving target. which is subfolder of the root archive folder for the FSA volume archiving target. For example. The default root archive folder path in the CurrentLocation property value represents the location of the FSA volume archiving target. ■ Double backslash (‘\\’) is used for preserving a backslash character in the folder path string. ■ Leading backslash characters will be ignored. ■ Public Folder archives. then the item is located in the folder "NewFolder". and the value of the CurrentLocation property is "\\FileSVR1.246 Content Management API IArchiveMetaData2 :: CurrentLocation The CurrentLocation property value does not contain any folder path elements for the default root archive folder. which is subfolder of "Inbox" archive folder. which is subfolder of the root archive folder for the SharePoint site collection target. 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 folder identified by CurrentLocation (or IContent::OriginalLocation. ■ If IContent::OriginalLocation property is omitted. ■ CurrentFolderId and CurrentLocation are optional. together with any missing parent folders. ■ When copying or moving an item. caller applications cannot manage folder level permissions using the Content Management API. Also. You can use the IArchive2::HasFolders property to determine if the archive is flat or has a folder structure. delete (if empty) and update archive folders are not currently available. or IContent::OriginalLocation (if the source archive is flat). copy or move operations. For insert. The caller must have write access on the destination archive in order to create new folders. then the ArchiveId property can be used instead of CurrentFolderId or CurrentLocation to define the archive folder for the item. 247 . then the destination archive folder is defined by IArchiveMetaData2::CurrentLocation (if the source archive contains a folder structure). it is created automatically. which do not contain folders). the value is populated with the path of the item's archive folder (insert operation). ■ CurrentFolderId and CurrentLocation are mutually exclusive.Content Management API IArchiveMetaData2 :: CurrentLocation If the CurrentLocation property is specified for a flat archive (for example. then the root folder of the archive is used. If neither of these properties is specified. then the property value returned is an empty string. or the path of the item's archive folder in the source archive (copy or move operation). Methods to enumerate. Which properties determine the current archive folder For item insert. create. folder permissions are inherited from the parent folder. 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. if the value of ArchiveId is an archive folder ID. shared or journal archives. when defaulting) has not yet been created. When creating new folders. Path of the specified CurrentFolderId from the Directory (It must be a folder in the archive) . Empty string) Archive Id Not specified Not specified Specified Folder matching Value of CurrentLocation OriginalLocation or property OriginalLocation property (Folder created as necessary .viz current refile behaviour) Archive Id Not specified Specified Not specified Folder matching CurrentLocation property (Folder created as necessary) Value of CurrentLocation property Archive Id Not specified Specified Specified Folder matching CurrentLocation property (Folder created as necessary) Value of OriginalLocation property Archive ID Specified Not specified Not specified Specified folder. move and copy operations ArchiveId Property CurrentFolderId CurrentLocation OriginalLocation Archived to Property Property Property folder Saveset OriginalLocation1 Archive Id Not specified Not specified Not specified Root folder "" (i.e.248 Content Management API IArchiveMetaData2 :: CurrentLocation Table 4-33 summarizes how the archive folder is determined when different combinations of the following properties are set: ■ IArchiveMetaData2::CurrentFolderId ■ IArchiveMetaData2::CurrentLocation ■ IContent::OriginalLocation Table 4-33 Determining the target archive folder for insert. Content Management API IArchiveMetaData2 :: CurrentLocation Table 4-33 Determining the target archive folder for insert. move and copy operations (continued) ArchiveId Property CurrentFolderId CurrentLocation OriginalLocation Archived to Property Property Property folder Saveset OriginalLocation1 Archive ID Specified Not specified Specified Specified folder. (It must be a folder in the archive) Archive folder ID Specified Not specified Specified Specified folder. Value of (It must be a OriginalLocation folder within the property archive) Archive ID Specified Specified Irrelevant Not supported. (It must be a folder in the archive) Path of the specified CurrentFolderId from the Directory Value of OriginalLocation property 249 . Value of OriginalLocation property (Folder created as necessary) Archive folder ID Specified Not specified Not specified Specified folder. Value of CurrentLocation property (Folder created as necessary) Archive folder ID Not specified Specified Specified Folder matching CurrentLocation property. error with invalid arguments2 Archive folder ID Not specified Not specified Not specified Folder specified in ArchiveId property Path of specified Archive folder ID from the Directory Archive folder ID Not specified Not specified Specified Folder specified in ArchiveId property Value of OriginalLocation property Archive folder ID Not specified Specified Not specified Folder matching CurrentLocation property. S_FALSE Success. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the request. // Identify ArchiveID of archive in which item is stored . Return value S_OK Success.Allowed if the archive folder ID associated with the specified CurrentLocation matches the specified CurrentFolderId value. 2. pCmAPI->get_Item(&pItem). This error indicates that the caller should retry later. The default value (NULL) is returned. Example [C++] IItem* pItem = NULL.250 Content Management API IArchiveMetaData2 :: CurrentLocation Determining the target archive folder for insert. or newVal is not a syntactically valid folder path.(CopyTo and MoveTo) If OriginalLocation is not specified. error with invalid arguments 2 1. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. move and copy operations (continued) Table 4-33 ArchiveId Property CurrentFolderId CurrentLocation OriginalLocation Archived to Property Property Property folder Archive folder ID Specified Specified Irrelevant Saveset OriginalLocation1 Not supported. then it is copied from the source item saveset value. retval] BSTR* pVal). Parameters [in] BSTR newVal The ID of the archive folder to set as current folder for the item. IArchiveMetaData2 :: CurrentFolderId This property specifies the ID of the archive folder in which the item is currently stored. archives that contain folders. or is to be stored when performing insert.Content Management API IArchiveMetaData2 :: CurrentFolderId CComBSTR ArchiveId (L"181E669473B52E64384C9A7D9EACA0E7E1110000evsite"). HRESULT CurrentFolderId ([out. pItem->put_ArchiveId(ArchiveId). Syntax HRESULT CurrentFolderId ([in] BSTR newVal). //Fetch the item's current archive folder path location CComBSTR CurrentLocation. CComQIPtr<IArchiveMetaData2> pAMD2(pAMD). // Identify Id of stored item CComBSTR ItemId (L" 161000000000000~200501051649270000~0~9039 eb282e3d4083b79f3298dc8a1e60") pItem->put_Id(ItemId). retval] BSTR* pVal The ID of the item's current archive folder. This property is only intended for use with structured archives. pItem->get_ArchiveMetaData(&pAMD). [out. copy or move item operations. that is. The property is read/write. 251 . pAMD2->get_CurrentLocation(&CurrentLocation). pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA ). IArchiveMetaDatat* pAMD = NULL. pCmAPI->get_Item(&pItem). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. then the property value is populated with the archive Id value after an Item property retrieval operation. each of the following properties can define the destination archive folder: ■ IArchiveMetaData2::CurrentLocation ■ IArchiveMetaData2:: CurrentFolderId ■ IContent::OriginalLocation See “IArchiveMetaData2 :: CurrentLocation” on page 245. Example [C++] IItem* pItem = NULL. S_FALSE Success. shared or journal archives. If the CurrentFolderId property is specified for a flat archive (for example. copy or move operations on structured archives. which do not contain folders). Return value S_OK Success. You can use the IArchive2::HasFolders property to determine if the archive is flat or has a folder structure. The default value (NULL) is returned. // Identify ArchiveID of archive in which item is stored CComBSTR ArchiveId . The property value is automatically populated by any of the following methods: ■ IItem::Insert ■ IItem::MoveTo ■ IItem::CopyTo For item insert.252 Content Management API IArchiveMetaData2 :: CurrentFolderId Remarks The Items collection object populates this property automatically. or newVal is an not a valid archive folder Id. It can be used to identify the start Index Sequence Number when enumerating collections of archived items using the Items collection object. //Fetch the item's current archive folder ID CComBSTR CurrentFolderId. retval] ULONGLONG* pVal) Parameters [out. pItem->get_ArchiveMetaData(&pAMD). See “IItems :: StartSequenceNum” on page 169. Remarks This property uniquely identifies the item in the archive. IArchiveMetaData2 :: SequenceNum This property specifies the Index Sequence Number of the archived item. CComQIPtr<IArchiveMetaData2> pAMD2(pAMD). The property is read only. pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA ).Content Management API IArchiveMetaData2 :: SequenceNum (L"181E669473B52E64384C9A7D9EACA0E7E1110000evsite"). pAMD2->get_CurrentFolderId(&CurrentFolderId). retval] ULONGLONG* pVal The Index Sequence Number (ISN) of the archived item. // Identify Id of stored item CComBSTR ItemId (L" 161000000000000~200501051649270000~0~9039 eb282e3d4083b79f3298dc8a1e60") pItem->put_Id(ItemId). IArchiveMetaDatat* pAMD = NULL. pItem->put_ArchiveId(ArchiveId). The Items collection object populatesthis property automatically. Syntax HRESULT SequenceNum ([out. This is useful for bulk moving or copying items. 253 . [C#] Item.Get((int)EV_STG_API_ITEM_DETAIL. Item.SequenceNum. Requirements Windows Server 2003 supports ULONGLONG types with OLE Automation.DETAIL_LEVEL_ARCHIVE_METADATA).ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite".Id = "200808070000000~200808070940280000~Z~BFA0C1B1FAB1468DB82 2E2473B4AAB05" Item.254 Content Management API IArchiveMetaData2 :: SequenceNum 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. ArchiveMetaData. but these types are not supported by Visual Basic Script. as items may have expired or been deleted. Example This example shows how to use the IArchiveMetaData2 interface to fetch the SequenceNUm property. . However ULONGLONG types are not supported on Windows Server 2000. . Return value S_OK Success. // Fetch the item's sequence no property // IArchiveMetaData2 IAMD2 = (IArchiveMetaData2)EVItem.NET managed code and C++ support ULONGLONG types. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. ulong SeqNo = EVIAMD2. retval] VARIANT* pVal). When copying or moving an item. Typically it is only set to retain the archived date when copying or moving items. The default value (0) is returned. S_FALSE Success. Syntax HRESULT ArchivedDate([in] VARIANT newVal). The property is read/write. To reset the achived date to the current date time. Return value S_OK Success. retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived date of this item Remarks Setting this property is optional. To specify an ArchivedDate when storing an item. simply set a null value on the destination ArchiveMetadata object. See “IItem :: CopyOptions” on page 187.Content Management API IArchiveMetaData2 :: ArchivedDate IArchiveMetaData2 :: ArchivedDate This property enables the caller to retrieve and set the original archived date and time (UTC) for the item. HRESULT ArchivedDate([out. Parameters [in] VARIANT newVal The required UTC date and time to be set for this item [out. the default action is to retain the item's archived date. Note: Setting the archived date can affect the item's retention period. 255 . set the ArchivedDate property value before calling the Insert method. Now().ArchivedDate = DateTime.Id ="334880000000000~200707251102240000~0~D3962A35951E4B03 AE9CFB68AFE1218".ArchiveMetaData. itemDst. itemDst. itemSrc. IItem itemDst = cmAPI.CopyTo(itemDst). itemSrc. or pVal is NULL.RetentionCategory = "Business". or an attempt was made to modify this property after the item had been stored in an archive.ArchiveId ="181E669473B52E64384C9A7D9EACA0E7E1110000ev site". Example IItem itemSrc = cmAPI. amd.ArchiveMetaData. Syntax interface ISimpleIndexMetadata : IDispatch . SimpleIndexMetadata object This object implements the following interface: ■ ISimpleIndexMetadata A SimpleIndexMetadata object is a collection of SimpleIndexProperty objects. itemSrc.ComplianceData.SetBy = EV_STG_API_CP_SETBY. and to enumerate the individual properties that belong to an item.ArchiveMetaData.256 Content Management API SimpleIndexMetadata object CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Supplied Variant type not VT_NULL or VT_DATE.Item. You can use the ISimpleIndexMetadata methods and properties to add new custom index properties before an item is archived.Item.SETBY_RETCAT. IArchiveMetaData2 amd = (IArchiveMetaData2)itemDest. 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.Content Management API SimpleIndexMetadata object 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. ToUTCTime Converts a local system time to UTC time. ToXML Returns the metadata in XML format. Clear Clears all properties from the SimpleIndexMetadata object for the current item. Remarks The type of properties returned in the collection can be controlled using the enumeration. EV_STG_API_ITEM_DETAIL. Examples [C#] 257 . Add Adds a value for a custom index property. on the Get method of the IItem interface. Table 4-35 ISimpleIndexMetadata methods Method Description Count Gives the number of custom index metadata properties for the current item. Searchable) propInfo = propInfo + vbCrlf + "Retrievable: " + CStr(idxprop.ArchiveMetaData. "Index Metadata" Err.Echo "No properties loaded!".Name propInfo = propInfo + vbCrlf + "Searchable: " + CStr(idxprop.Set + vbCrLf + "Name: " + idxprop.number <> 0) then WScript.number) + vbCrLf + "Description: " + Err.Echo "Enumerating failed!" + vbCrLf + "Reason: " + Hex(Err.258 Content Management API SimpleIndexMetadata object IArchiveMetaData amd = item.IndexData if (IMData.Retrievable) pVal = idxprop.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. vbOKOnly.Clear else ‘Use local system date/times IMData. "Index Metadata" Err. The following VBScript excerpt gives an example of how metadata can be read from the instance returned by Content Management API: [VBScript] [C#] ‘ Get the Index Metadata from the retrieved item Set IMData = oItem. vbOKOnly + vbExclamation.Description.IndexData.Count() = 0) then WScript. ISimpleIndexMetadata simple = amd.ArchiveMetaData. "Index Metadata Properties List" next if (Err.Clear end if end if .Echo propInfo. vbOKOnly + vbExclamation.Value propInfo = propInfo + vbCrLf + "Value (" + TypeName(pVal) + "): " + CStr(pVal) WScript. Parameters [out. This property is hidden in Visual Basic Scripting Edition (VBScript). Remarks This property is a standard property used to support enumerating collections. See also ■ See “SimpleIndexProperty object” on page 269. A collection of SimpleIndexProperty objects is returned. 259 . CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive property value.dll. ■ See “IItem :: Get” on page 194.retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object. ISimpleIndexMetadata :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the SimpleIndexMetadata collection object. Syntax HRESULT _NewEnum([out. or VBScript. ■ See “Adding custom index metadata” on page 72. Return value S_OK Success.Content Management API ISimpleIndexMetadata :: _NewEnum Requirements Implemented in KVS.EnterpriseVault. The property is read only.retval] IUnknown** enumerator).Common. it is automatically used internally when you use the For Each construct in C#. . DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.Name. bool retrievable = ip.ArchiveMetaData.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". item. IArchiveMetaData amd = item.Searchable.Item. //do something with the values obtained } ISimpleIndexMetadata :: DateTimesUTC This boolean property sets or retrieves whether the date and time properties are input and output in UTC or local system time. Parameters [out. string name = ip.IndexData. ISimpleIndexMetadata simple = amd. retval] VARIANT_BOOL* pRetVal Whether time property values are UTC times or as local system times. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))). item. HRESULT DateTimesUTC([in] VARIANT_BOOL pRetVal). retval] VARIANT_BOOL* pRetVal).Value.Set.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". [in] VARIANT_BOOL pRetVal Whether time property values are UTC times or as local system times.Retrievable.260 Content Management API ISimpleIndexMetadata :: DateTimesUTC Example IItem item = cmAPI. Syntax HRESULT DateTimesUTC([out.Get((int)((EV_STG_API_ITEM_DETAIL. foreach (ISimpleIndexProperty ip in simple) { string set = ip. item. bool searchable = ip. object val = ip. Item.Content Management API ISimpleIndexMetadata :: Count Remarks By default.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". Example ‘Use local system date/times IMData. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL. retval] long* pRetVal). Parameters [out. item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. items are always archived using UTC time. 261 . Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL. item. Return value S_OK Success. retval] long* pRetVal Number of custom index metadata properties.DateTimesUTC = false ISimpleIndexMetadata :: Count This method gives the number of custom index metadata properties for the current item. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))). item. Example IItem item = cmAPI. Syntax HRESULT Count([out. [in] BSTR propertyName. If no property set is specified. [in] VARIANT_BOOL propertySearchable. Parameters [in] BSTR propertySet Name of the property set to which the property belongs.IndexData. the property is added to the default (global) property set. . [in] BSTR propertyName Name of the property. ISimpleIndexMetadata simple = amd. A Variant containing a value of any of the supported types listed in Table 4-36. [in] VARIANT propertyValue Property value.262 Content Management API ISimpleIndexMetadata :: Add IArchiveMetaData amd = item.ArchiveMetaData. Syntax HRESULT Add [in] BSTR propertySet. The Search API can be used to search for specific index data. [in] VARIANT_BOOL propertyRetrievable). if (simple. or is to be added. [in] VARIANT propertyValue. The property is then available in the index document for the item.Count> 0) { //do something ISimpleIndexMetadata :: Add This method is used to add a custom index property to an item before it is archived. or VT_DECIMAL Limited to the range 0 to 4. the property will be added to the property set specified by the propertySet parameter. [in] VARIANT_BOOL propertyRetrievable Defines whether the property values can be requested in search results. The method can be called repeatedly to add multiple properties or to add multiple values to the same property. 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.294 Remarks Custom index data can only be added when the item is inserted. VT_UI2. VT_UI8. VT_I4. Setting the value of this property to true means that the property will be indexed. VT_UI4. Setting the value to true means that property information can be retrieved and displayed later with the item in search results. VT_I8.294. VT_I2. VT_UINT. The default value is false. If a property set is specified that does not exist. copied or moved. VT_I1. VT_INT. The default value is true. It is not possible to update custom index data for an archived item. then the property set will be created and the property and value will be added to that new set. When you use Add to add a property to the index.Content Management API ISimpleIndexMetadata :: Add [in] VARIANT_BOOL propertySearchable Defines whether the property is added to the item index. Suitable 263 .967. Table 4-36 Supported types for propertyValue Value type Variant type Note String VT_BSTR dateTime VT_DATE Limited to the UTC date range 1st January 1970 to 1st January 2038 Integer VT_UI1. Content. IContent content = item. "My name". IArchiveMetaData amd = item. .ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". or propertyName is NULL or an empty string. content. content. 32.ArchiveMetaData.OriginalLocation = "Inbox".Data = "C:\\temp\\test.Insert(). ISimpleIndexMetadata simple = amd. //add some custom index data simple.Title = "New title".264 Content Management API ISimpleIndexMetadata :: Add names would be your company name or the application name. true). for example out of supported range.IndexData. content.Add("My set". CONTENTMANAGEMENTAPI_E_BAD_PARAMETER propertySet is NULL. Return value S_OK Success. Example item. true.FileExtension = "msg". content. See “Adding custom index metadata” on page 72. The following property set names are reserved: ■ Vault ■ EnterpriseVault ■ Any property set name starting with EV ■ KVS ■ Veritas ■ Symantec Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. item.msg". or propertyValue is NULL or an invalid type or is an invalid value. Content Management API ISimpleIndexMetadata :: Clear ISimpleIndexMetadata :: Clear This method is used to clear all properties from the SimpleIndexMetadata object for the current item.DETAIL_LEVEL_CUSTOM_INDEX_METADATA))).DETAIL_LEVEL_ARCHIVE_METADATA) | ( EV_STG_API_ITEM_DETAIL. IArchiveMetaData amd = item. 265 . simple. Return value S_OK Success. item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Get((int)((EV_STG_API_ITEM_DETAIL. the XML returned will be in human-readable format. Syntax HRESULT ToXML( [in] VARIANT_BOOL formattedLayout. Example IItem item = cmAPI.ArchiveMetaData. [out. [out.Clear(). item. ISimpleIndexMetadata :: ToXML This method returns the metadata in XML format. ISimpleIndexMetadata simple = amd. retval] BSTR* pRetVal An XML string is returned.Item. retval] BSTR* pRetVal).IndexData. item. Parameters [in] VARIANT_BOOL formattedLayout If true. Syntax HRESULT Clear(). Add "Egapp".Data = "c:\data file. Examples The following code excerpt gives an example of how metadata can be added and returned as XML. "EgApplication".DateTimesUTC = false ‘ Add a property called Agent..266 Content Management API ISimpleIndexMetadata :: ToXML Return value S_OK Success. false.ComplianceData. "File".Content..Echo IMData. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL. "EgFilename".true. "TimeStamp".ArchiveMetaData. ‘ "EgApplication" to the default.IndexData IMData. true ‘ Add the following properties to the property set called "EgApp".ArchiveMetaData.SetBy = RetCat Dim IMData set IMData = oItem. with the string value.ToXML(true) oItem. true IMData.RetentionCategory = "Technical Documents" oItem.Content.Item oItem.doc" oItem. This property ‘ is searchable and retrievable.ContentManagementAPI") Dim oItem set oItem = ecmAPI. false. IMData. CDate("2006-10-23 12:00:00").Add "EgApp".ArchiveMetaData.doc" oItem.ArchiveId = "137100ED24187DB43A884B0C0B8D3FF511110000EVServer" // populate the Data property from a file oItem.Insert() // actually performs the insert . using the ToXML method: Option Explicit ‘On Error Resume Next Dim ecmAPI Set ecmAPI = CreateObject("EnterpriseVault.Add vbNullString. true ‘ return the property information as formatted XML WScript. IMData. . "Agent".Title = "function design document. global property set.Clear ‘ Use local date and time IMData. The XML schema is not published. Parameters [in] BSTR xmlIndexMetadata The XML stream to input. Syntax HRESULT FromXML([in] BSTR xmlIndexMetadata). ISimpleIndexMetadata :: FromXML This method enables you to load a set of properties that have previously been defined and stored using the ToXML method. Figure 4-3 ToXML result See also ■ See “ArchiveMetaData object” on page 225.Content Management API ISimpleIndexMetadata :: FromXML The ToXML method in this example would display the custom metadata as formatted XML. as shown in Figure 4-3. Remarks Use the Add method to add item specific values. as the Add method should always be used to add metadata properties. 267 . CONTENTMANAGEMENTAPI_E_BAD_PARAMETER xmlIndexMetadata supplied as NULL.Content.Title = "New title". Example item. ISimpleIndexMetadata :: ToLocalTime This is a helper method to convert a UTC time to local system time. .FileExtension = "msg". ISimpleIndexMetadata simple = amd.268 Content Management API ISimpleIndexMetadata :: ToLocalTime Return value S_OK Success. IArchiveMetaData amd = item. or is invalid XML. //xmlData is a pre-populated string containing the xml item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite". IContent content = item. FromXML(xmlData).msg". Syntax HRESULT ToLocalTime( [in] DATE utcDateTime.ArchiveMetaData.IndexData.OriginalLocation = "Inbox". content.Data = "C:\\temp\\test. //add some custom index data from xml simple.Insert(). [out. Parameters [in] DATE utcDateTime The UTC date and time to convert. retval] DATE* pRetVal The local date and time are returned. retval] DATE* pRetVal). content. content. [out. content. or utcDateTime is not a syntactically valid UTC date time value. retval] DATE* pRetVal). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL. retval] DATE* pRetVal The local date and time are returned. Syntax HRESULT ToUTCTime( [in] DATE localDateTime.or localDateTime is not a syntactically valid local date time value. SimpleIndexProperty object The SimpleIndexProperty object implements the following interface: ■ ISimpleIndexProperty 269 . Return value S_OK Success.Content Management API ISimpleIndexMetadata :: ToUTCTime Return value S_OK Success. Parameters [in] DATE localDateTime The local date and time to convert. [out. ISimpleIndexMetadata :: ToUTCTime This is a helper method to convert a local system time to UTC date and time. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL. [out. The property is read only. Example IArchiveMetaData amd = item. Retrievable Read only Whether the property can be included in search results.270 Content Management API ISimpleIndexProperty :: Set Syntax interface ISimpleIndexProperty : IDispatch Member summary This read-only interface has the following properties defined: Table 4-37 ISimpleIndexProperty properties Parameter Read/Write Description Set Read only Name of the property set.IndexData. . Name Read only Name of the property. Searchable Read only Whether the property is to be added to the item index. foreach (ISimpleIndexProperty ip in simple) { ISimpleIndexProperty :: Set This property returns the property set name. Remarks Properties added to the item index using the Add method of the ISimpleIndexMetadata interface are held as SimpleIndexProperty objects.ArchiveMetaData. Value Read only Value assigned to the property. System Read only Whether the property is one that is indexed by default during the archiving process. ISimpleIndexMetadata simple = amd. item.Name. Remarks If empty.Retrievable. the property is a member of the global property set. Example IItem item = cmAPI. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))).Value.Content Management API ISimpleIndexProperty :: Set Syntax HRESULT Set([out. string name = ip. Parameters [out.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". retval] BSTR* value).Searchable. foreach (ISimpleIndexProperty ip in simple) { string set = ip. retval] BSTR* value Property set name. Return value S_OK Success.Set. bool retrievable = ip. item. item.ArchiveMetaData. ISimpleIndexMetadata simple = amd. //do something with the values obtained } 271 . object val = ip. IArchiveMetaData amd = item. DETAIL_LEVEL_ARCHIVE_METADATA) | EV_STG_API_ITEM_DETAIL.Get((int)((EV_STG_API_ITEM_DETAIL.Item. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value. bool searchable = ip.IndexData.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". the value is another instance of a SimpleIndexMetadata object. detailing the index properties of the attachment. or a custom name. The first attachment on a nested message would be "1. Remarks The name of a property can be a predefined name.1". 1. If the property is a top-level message. such as IndexPropSUBJ. Figure 4-4 illustrates the naming convention for messages and attachments. the numeric identification of an attachment (for example.1". Parameters [out. The property is read only. then the Name is "1".2 and so on). 1.272 Content Management API ISimpleIndexProperty :: Name ISimpleIndexProperty :: Name This property returns the property name. which may be a file or a message.retval] BSTR* value).1.1). In this case.1. The first attachment would be "1. Syntax HRESULT Name([out. then the property refers to a message attachment. If the value is a formatted number (1. . 1.retval] BSTR* value Name of the property. 273 .2 1.1. The value of this property differs from the property Name. The property.3 1.1 Each of the nested items has their own set of properties.1.1 1. IndexPropANUM.1 1.2.2. also contains the numeric identity of a message attachment.2 1. Figure 4-5 shows the values of IndexPropANUM for a message with an attached document and an attached message. which can be enumerated.1.1 1. which also has attached documents.Content Management API ISimpleIndexProperty :: Name Naming format for messages Figure 4-4 Top-level message 1 Message Attachments 1. and Enterprise Vault 6.0 SP3 and Enterprise Vault 2007 SP1. Return value S_OK Success.0 SP3. See “Enterprise Vault 2007 SP1. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1. the COMR (content missing) property is returned in the index data. See “Note 4” on page 610.0 SP3. Enterprise Vault 7.274 Content Management API ISimpleIndexProperty :: Name Example values of IndexPropANUM Figure 4-5 Top-level message anum=0 Message attachments anum=1 anum=4 anum=7 Anum anum=2 =3 anum=5 anum=6 If content items are missing. Version information ■ Numeric identity of a message attachments in IndexPropANUM is available in Enterprise Vault 7. ■ Content missing reasons returned in the index data COMR property is available in Enterprise Vault 7.0 SP5” on page 40. . Enterprise Vault 7.0 SP5” on page 40. and Enterprise Vault 6. The value of this property indicates the reason for the missing content. 0 SP4” on page 42. item. item. See “Enterprise Vault 2007.Searchable.0 SP2.IndexData. and Enterprise Vault 6. object val = ip.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ArchiveMetaData. ISimpleIndexProperty :: Value This property returns the property value. foreach (ISimpleIndexProperty ip in simple) { string set = ip. item. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. ISimpleIndexMetadata simple = amd.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Get((int)((EV_STG_API_ITEM_DETAIL. string name = ip. the value of ISimpleIndexProperty :: Name can be a formatted number (1. 1. Syntax HRESULT Value([out.0 SP2.Item.1. bool retrievable = ip.Content Management API ISimpleIndexProperty :: Value ■ For a message attachment.Value.Set. bool searchable = ip. 1. //do something with the values obtained } See also ■ See “System properties” on page 596.Retrievable.retval] VARIANT* value). Enterprise Vault 7.0 SP4 and Enterprise Vault 7. Example IItem item = cmAPI. 275 .2 and so on) in Enterprise Vault 6. DETAIL_LEVEL _CUSTOM_INDEX_METADATA))). IArchiveMetaData amd = item. The property is read only.Name. VT_I4. VT_UI8. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value. .retval] VARIANT* value Table 4-38 Property value. which may be a file or a message.294 SimpleIndexMetadata object VT_UNKNOWN Note An ISimpleIndexProperty instance Remarks If the Name property is a formatted number (1. VT_I2. VT_I1.276 Content Management API ISimpleIndexProperty :: Value Parameters [out. In this case. VT_UI2. VT_UINT. VT_INT. VT_UI4. A Variant containing a value of any of the supported types listed in Table 4-38. See “Adding custom index metadata” on page 72. Supported types for Value Value type Variant type String VT_BSTR Datetime VT_DATE Limited to the UTC date range 1st January 1970 to 1st January 2038 Integer VT_UI1. item.Item. Example IItem item = cmAPI.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". or VT_DECIMAL Limited to the range 0 to 4.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". then the property refers to a message attachment. VT_I8. detailing the index properties of the attachment.2 and so on). the Value property is a SimpleIndexMetadata object. Hints and tips on adding custom index properties are provided in the introduction to the Content Management API.967.1. item. Return value S_OK Success. 1.294. string name = ip. Parameters [out.IndexData. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))).retval] VARIANT_BOOL* value). object val = ip. Syntax HRESULT Searchable([out. The property is read only. //do something with the values obtained } ISimpleIndexProperty :: Searchable This property returns whether the property is indexed. 277 . ISimpleIndexMetadata simple = amd.Set. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.Searchable.retval] VARIANT_BOOL* value Return value S_OK Success.Get((int)((EV_STG_API_ITEM_DETAIL. IArchiveMetaData amd = item. foreach (ISimpleIndexProperty ip in simple) { string set = ip.ArchiveMetaData.Content Management API ISimpleIndexProperty :: Searchable item. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.Retrievable.Name. and hence can be searched for using the Search API. bool searchable = ip.Value. bool retrievable = ip. item. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))).ArchiveMetaData. item. bool searchable = ip.Name. bool retrievable = ip. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.Get((int)((EV_STG_API_ITEM_DETAIL. foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set.IndexData.retval] VARIANT_BOOL* value). Parameters [out. item. //do something with the values obtained } See also ■ See “System properties” on page 596. The property is read only.Searchable.retval] VARIANT_BOOL* value . Syntax HRESULT Retrievable([out.Item.Value.278 Content Management API ISimpleIndexProperty :: Retrievable Example IItem item = cmAPI.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". ISimpleIndexMetadata simple = amd. ISimpleIndexProperty :: Retrievable This property returns whether the property can be retrieved and displayed with search results in the search application. string name = ip.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". object val = ip. IArchiveMetaData amd = item.Retrievable. IndexData. //do something with the values obtained } See also ■ See “System properties” on page 596. 279 . bool retrievable = ip. string name = ip. Example IItem item = cmAPI. See “System properties” on page 596. bool searchable = ip.Item. The property is read only.Get((int)((EV_STG_API_ITEM_DETAIL.Name.Set. IArchiveMetaData amd = item. object val = ip.DETAIL_LEVEL_CUSTOM_INDEX_METADATA))).ArchiveMetaData. ISimpleIndexMetadata simple = amd. item. item.Value.Content Management API ISimpleIndexProperty :: System Return value S_OK Success. item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Retrievable. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.Searchable. foreach (ISimpleIndexProperty ip in simple) { string set = ip. ISimpleIndexProperty :: System This property indicates that the property is an Enterprise Vault system property. System. Return value S_OK Success.Searchable. bool isSystem = ip. foreach (ISimpleIndexProperty ip in simple) { string set = ip. IArchiveMetaData amd = item. item. the value of System is always false.Name. item. bool searchable = ip. ISimpleIndexMetadata simple = amd.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Item. //do something with the values obtained } . string name = ip.Get((int)((EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA) | (EV_STG_API_ITEM_DETAIL. Example IItem item = cmAPI. item. DETAIL_LEVEL_SYSTEM_INDEXDATA))). bool retrievable = ip.IndexData. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value. object val = ip.280 Content Management API ISimpleIndexProperty :: System Syntax HRESULT System([out.Set.ArchiveMetaData.retval] VARIANT_BOOL* value Remarks For custom properties that are added using Add.Value.retval] VARIANT_BOOL* value).Retrievable. Parameters [out.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. ArchiveMetaData.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". or not set. for example. Syntax interface IComplianceData : IDispatch Remarks The IComplianceData interface is for use only with compliance devices.Item. item. years. item. IComplianceData compData = amd. ComplianceData object This object implements the following interface: ■ IComplianceData The IComplianceData interface is obtained by using the ComplianceData property of the IArchiveMetaData interface. the retention category. days. .Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". Example IItem item = cmAPI. Units Read/Write Specifies the compliance period units. months. SetBy Write only Defines where the compliance period is set.ComplianceData. weeks. the ComplianceData object. IArchiveMetaData amd = item. item. Member summary Table 4-39 IComplianceData properties Property Read/Write Description Value Read/Write Combined with the Units property specifies the duration of the compliance period. DETAIL_LEVEL_ARCHIVE_METADATA).Content Management API ComplianceData object 281 See also ■ See “System properties” on page 596.Get((int)EV_STG_API_ITEM_DETAIL. Remarks EV_STG_API_CP_UNITS indicates the units used in specifying the compliance period. Example IItem item = cmAPI.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.Item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". item. Parameters [out. HRESULT Units([in] EV_STG_API_CP_UNITS newVal). item. See “EV_STG_API_CP_UNITS enumeration” on page 80. The property is read/write. combined with the Value property.Get((int)EV_STG_API_ITEM_DETAIL. Syntax HRESULT Units([out. specifies the duration of the compliance period. Return value S_OK Success. 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. . item. retval] EV_STG_API_CP_UNITS* pVal). or the value passed in to the property does not match one of the enumeration values.282 Content Management API IComplianceData :: Units IComplianceData :: Units This property. Syntax HRESULT Value([out. IArchiveMetaData amd = item. Parameters [out. retval] VARIANT* pVal).ComplianceData. 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. IComplianceData compData = amd.Content Management API IComplianceData :: Value DETAIL_LEVEL_ARCHIVE_METADATA). for a compliance period of 6 days. The property is read/write. object obj = compData. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. Value = 6 and Units = CP_UNITS_DAYS Return value S_OK Success. or newVal is invalid. combined with the Units property.Units. 283 . IComplianceData :: Value This property. HRESULT Value([in] VARIANT newVal).Value.ArchiveMetaData. specifies the duration of the compliance period. EV_STG_API_CP_UNITS evUnits = compData. ulong val = (ulong)obj. IComplianceData compData = amd.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". EV_STG_API_CP_UNITS evUnits = compData.ComplianceData.284 Content Management API IComplianceData :: SetBy Example IItem item = cmAPI.Get((int)EV_STG_API_ITEM_DETAIL. Syntax HRESULT SetBy([in] EV_STG_API_CP_SETBY newVal). ulong val = (ulong)obj.Item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". item. The property is write only. . 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. Return value S_OK Success. DETAIL_LEVEL_ARCHIVE_METADATA). IComplianceData :: SetBy This property indicates where the retention period was defined.Value. item. object obj = compData. item. IArchiveMetaData amd = item. This property should only be used during a copy/move operation and should not be called once an item has added to the archive. See “EV_STG_API_CP_SETBY enumeration” on page 79.Units.ArchiveMetaData. or the value passed in does not conform to one of the enumeration type values. remove holds from items and enumerate all existing holds on an item. remove existing holds and list the holds that have been placed on items in a vault store. for example. ■ Metadata. to provide additional information about the hold. 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. The Group ID could. Existing functionality in Discovery Accelerator allows the administrator to put items on hold. These interfaces allow Enterprise Vault Accelerator products and third-party applications to put items on hold. items that are placed on hold cannot be deleted by a user or by Enterprise Vault (using storage expiry). The IHolds2 interface inherits from IHolds. ■ A Group ID. Items can be placed on hold by specifying the following: ■ A Consumer ID. which returns information in XML about the success or failure of removing holds on items in each vault store. 285 . to identify the group of items with a particular hold applied. and provides the method ReleaseHolds2. to identify the calling application. 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).Content Management API Holds object CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Invalid pointer passed to receive property value. Legal Hold functionality is provided by the IHolds and IHold interfaces in the Content Management API. identify the legal case. and this information could then be accessed by other consumers. ■ By supplying the Consumer ID and a list of Hold IDs of items from which the consumer wants to remove holds.next loop.Holds property.. for example: <MetaData> <Reason Value="John Doe against EG Corp" /> </MetaData> Using the IItem. Holds may be removed from items in two ways: ■ By specifying the Consumer ID and the Group ID. Member summary Table 4-40 IHolds Properties Property Description _NewEnum This property gives access to an IEnumVariant interface (which acts an enumerator) and allows script clients to enumerate the collection of IHold interface pointers and iterate through the collection using a for. The metadata is in XML format. GroupId The GroupId property is set to identify a group of holds placed at one time. This allows the consumer to remove holds from items in batches rather than a whole group at once. For example. metadata could be used to say why one consumer has put the item on hold. The same GroupId used to place holds can also be used to release all the holds in that group. This will remove all holds which have been placed on an item with the supplied Consumer ID and Group ID. ConsumerGUID The ConsumerGUID is the unique identifier of the application calling the API. This would typically be an identifier of a particular legal case. for example.. an application can enumerate all the holds which have been placed on an item. Count This read only property returns the number of IHolds in the collection. .286 Content Management API Holds object ■ The list of items that the calling application wants to place on hold. 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. Item This property gives access to a particular instance of IHold in the collection using the index. The metadata may be useful when there are several consumers of the Legal Hold API at the same time. 0 SP1.retval] IUnknown** enumerator). Version information IHolds2 interface requires Enterprise Vault 8. This property is hidden in Visual Basic Scripting Edition (VBScript). See also See “Hold object” on page 300. ReleaseHolds Releases a hold on each item in the collection. The same metadata will be applied to each hold in the group. Table 4-41 IHolds Methods Method Description Add Adds an IHold interface pointer to the collection. PlaceHolds Places a hold on each item in the collection.Content Management API IHolds :: _NewEnum Table 4-40 IHolds Properties (continued) Property Description Metadata The metadata property contains the metadata to be passed with the holds to the Enterprise Vault server. IHolds :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the IHolds collection object. Syntax HRESULT _NewEnum([out. in XML format. and returns success or failure information. Table 4-42 IHolds2 Method Method Description ReleaseHolds2 Releases a hold on each item in the collection. The property is read only. for each vault store processed. 287 . Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive property value. Remarks This property is a standard property used to support enumerating collections.Holds.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". it is automatically used internally when you use the For Each construct in C#. retval] LPVARIANT pRetVal). IHolds holds = Item. item.retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". foreach (IHold hold in holds) { IHolds :: Item This property gives access to a particular hold in a collection. A collection of IHold objects is returned. Example IItem item = cmAPI. The property is read/write. item. Syntax HRESULT Item([in] VARIANT index. item. HRESULT Item([out. .288 Content Management API IHolds :: Item Parameters [out. DETAIL_LEVEL_HOLD_DATA). or VBScript.Get((int)EV_STG_API_ITEM_DETAIL.Item. The property is read only. Example IItem item = cmAPI. i++) { IHold hold = (IHold)holds. 289 . i < holds.Item. retval] LPVARIANT pRetVal Pointer to a VARIANT that will return the current index value. item. IHolds :: Count This read only property returns the number of Holds in the collection. for (int i = 0. Remarks The VARTPYE of this property should be vt = VT_I4.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Holds.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Get((int)EV_STG_API_ITEM_DETAIL. Note that the index supplied to the property is 1-based not 0-based. or data type of variant was incorrect. or index is out of range.Content Management API IHolds :: Count Parameters [in] VARIANT index VARIANT holding the value of the index of the required hold. item. IHolds holds = Item. [out.Item(i + 1). DETAIL_LEVEL_HOLD_DATA). Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pRetVal pointer is NULL.Count . item. DETAIL_LEVEL_HOLD_DATA).retval] BSTR* pVal). for (int i = 0.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". item.290 Content Management API IHolds :: GroupId Syntax HRESULT Count([out. Example IItem item = cmAPI. The property is read/write.Count . . item.Item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Get((int)EV_STG_API_ITEM_DETAIL. Return value S_OK Success. item. for example.Item(i + 1). i < holds. This would typically be an identifier of a particular legal case. IHolds :: GroupId This property is set to identify a group of holds placed at one time. i++) { IHold hold = (IHold)holds. Syntax HRESULT GroupId([in] BSTR newVal). retval] long* pRetVal). IHolds holds = Item. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pRetVal pointer is NULL. Parameters [out. HRESULT GroupId([out. retval] long* pRetVal Current number of holds in the collection.Holds. Add(hold). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. A GroupId should consist of printable characters and should not contain any of the following characters: <> & ' " Return value S_OK Success. holds.GroupId = "Group 1". [out.retval] BSTR* pVal Pointer to a BSTR that will contain the current group Id.PlaceHolds().Content Management API IHolds :: GroupId Parameters [in] BSTR newVal BSTR containing the new group Id.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". 291 . or newVal contains invalid characters.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". Example IHolds holds = cmAPI. holds. holds. IHold hold = cmAPI.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}".Holds. holds.MetaData = "Some metadata". or one or more holds have already been placed for the current group. //add more hold's if necessary holds.Hold. hold. Remarks The same GroupId used to place holds can also used to release all the holds in that group. hold. Holds.292 Content Management API IHolds :: ConsumerGUID IHolds :: ConsumerGUID This property is the unique identifier of the application calling the API. Syntax HRESULT ConsumerGUID([in] BSTR newVal). Return value S_OK Success.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.MetaData = "Some metadata". Set by caller. holds. holds. [out. It must be set before holds can be placed or released. IHold hold = cmAPI.retval] BSTR* pVal).ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}". The property is read only. Parameters [in] BSTR newVal BSTR containing any valid GUID value. Example IHolds holds = cmAPI.Hold. holds. .GroupId = "Group 1". 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. HRESULT ConsumerGUID([out. PlaceHolds(). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER An attempt was made to modify this property once the PlaceHolds had been called. //add more hold's if necessary holds.retval] BSTR* pVal). Parameters [in] BSTR newVal BSTR containing the new MetaData value. 293 .Content Management API IHolds :: Metadata hold. Return value S_OK Success. [out. IHolds :: Metadata This property contains the metadata to be passed with the holds to the Enterprise Vault server.retval] BSTR* pVal Pointer to a BSTR that will contain the current value of the metadata. hold. Syntax HRESULT Metadata([in] BSTR newVal).ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Add(hold). holds. Remarks The same metadata will be applied to each hold in the group. The property is read/write. HRESULT Metadata([out. ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".PlaceHolds(). hold. //add more hold's if necessary holds.Hold. IHold hold = cmAPI.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}". Remarks The IHold interface pointer must be obtained through the IContentManagementAPI property.[in] IHold* newHold IHold interface pointer to add to the collection.MetaData = "Some metadata". hold.Add(hold). holds. holds.Holds. . holds. IHolds :: Add This method allows a client to add a new hold to the collection.GroupId = "Group 1". holds. Syntax HRESULT Add([in] IHold* newHold). Hold.294 Content Management API IHolds :: Add Example IHolds holds = cmAPI. Parameters . Return value S_OK Success. Syntax HRESULT PlaceHolds(). Transaction Id or Hold Id.GroupId = "Group 1". or it has already been added with this Saveset Id. //add more hold's if necessary holds. Remarks After the call has been placed.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". holds. hold. IHold hold = cmAPI. Return value S_OK Success.MetaData = "Some metadata". hold. IHolds :: PlaceHolds This function is used to actually place a hold on each item in the collection.Hold.Content Management API IHolds :: PlaceHolds CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Hold object has been used. 295 . holds.PlaceHolds().ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}".ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". holds.Holds. holds. any errors in placing holds are reported in the Status property of the hold objects in the collection.Add(hold). Example IHolds holds = cmAPI. IHold hold = cmAPI. holds.Hold. Example IHolds holds = cmAPI. This error indicates that the caller should retry later. holds.Holds.296 Content Management API IHolds :: ReleaseHolds CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed to receive the property value. . IHolds :: ReleaseHolds This function is used to release a hold on each item in the collection. //add more hold's if necessary holds. hold. Syntax HRESULT ReleaseHolds(). or there is an error with the ConsumerGUID. the groupId is missing. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the request. holds. holds.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".PlaceHolds().ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}".MetaData = "Some metadata".ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Add(hold).GroupId = "Group 1". CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. hold. or the hold is already placed. and any of the holds within a vault store fails to be released. 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. then the whole group is considered to have failed. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. the caller can interrogate the Hold objects in the group to find out what went wrong (using the Status property). Note that some holds may actually have been released. you must also call ReleaseHolds( ) specifying the GroupId as before. but the caller will need to repeat the release on the group as whole until it succeeds. 297 .or the consumer GUID is incorrect. When using a GroupId. when all holds in a group are eventually released. after establishing the reason for failure and correcting it. or the object has already been used. or if the groupId has been set then the DNS alias has not been set.Content Management API IHolds :: ReleaseHolds Remarks The IContentManagementAPI :: DirectoryDNSAlias property should be set by the caller before releasing holds by GroupId. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointerhas been passed to receive property value. When not using a GroupId. Finally. This error indicates that the caller should retry later. all the holds in the vault store will also be marked as failed. Return value S_OK Success. if any of the holds in the group fail to be released. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the request. In this case. then to dispose of the group itself. if the holds are spread over multiple vault stores. but the caller will need to repeat the release on the group as whole until it succeeds. Remarks The IContentManagementAPI :: DirectoryDNSAlias property should be set by the caller before releasing holds by GroupId. IHolds holds = cmAPI. then the whole group is considered to have failed. When not using a GroupId.DirectoryDNSAlias = "SERVER1".GroupId = "Group 1". Parameters [out. holds. . holds. then to dispose of the group itself.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}". you must also call ReleaseHolds2( ) specifying the GroupId as before. if any of the holds in the group fail to be released. for each vault store in which items were processed. holds.Holds. in that it can be used to release a hold on each item in a collection.ReleaseHolds(). Finally. in XML. if the holds are spread over multiple vault stores.298 Content Management API IHolds2 :: ReleaseHolds2 Example cmAPI. but this method also returns a summary status report. retval] BSTR* pVal). after establishing the reason for failure and correcting it. Note that some holds may actually have been released.retval] BSTR* pVal Pointer to a BSTR that will contain the status report in XML. and any of the holds within a vault store fails to be released. Syntax HRESULT ReleaseHolds2([out. IHolds2 :: ReleaseHolds2 This method is similar to ReleaseHolds. When using a GroupId. all the holds in the vault store will also be marked as failed. 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 all holds in a group are eventually released. ReleaseHolds2(). or the object has already been used. the vault store is identified by the Id field. Examples cmAPI. then the HRESULT returned for the vault store is 0. 299 . holds2.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}".0 SP1. or if the groupId has been set then the DNS alias has not been set. In the XML.Holds. This error indicates that the caller should retry later. Version information ReleaseHolds2 method requires Enterprise Vault 8.Content Management API IHolds2 :: ReleaseHolds2 The XML returned by the method indicates the success or failure of the action for each vault store as a whole. and success or failure of the operation is indicated by the hr field (HRESULT). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointerhas been passed to receive property value. If the hold could not be released on some or all of the affected items in the vault store. CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault is currently busy or has insufficient resource to complete the request. holds2.DirectoryDNSAlias = "SERVER1". CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. Return value S_OK Success.or the consumer GUID is incorrect. string xml holds2.GroupId = "Group 1". IHolds2 holds = (IHolds2)cmAPI. If the hold was released successfully on all affected items in a vault store. then the hr field contains the error code value. com" hr="0"/> </VaultStores> 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. <VaultStores> <VaultStore Id="16918E349851B39307B57E2FC4603DDB2121 0000VS2. This property must be set before a hold is placed or released. The HRESULT returned for the second vault store is not zero.300 Content Management API Hold object The following example shows XML returned by ReleaseHolds2. Syntax interface IHold : IDispatch Member summary Table 4-43 IHold properties Property Description ArchiveId This property specifies the ArchiveID where the item to which this hold object refers is stored. This property must be set before a hold is placed. .eg. indicating that the attempt to release the hold on items in this vault store failed.com" hr="0"/> <VaultStore Id="157E2F1B39307B86918E3498C4603DDB2121 0000VS2. ItemId This property specifies the identifier of the item to which this hold object refers.com" hr="0x80040300"/> <VaultStore Id="1B39307B86918E3498557E2FC4603DDB2121 0000VS. and must be set before a hold can be released. It is a collection of IHold interface pointers that are stored in the IHolds collection.eg. It is returned once a hold has been placed.eg. Status This read only property returns the status of the hold after an attempt either to place or release a hold. Id This property identifies the hold object. hold. is stored. Example IHold hold = cmAPI. retval] BSTR* pVal). Syntax HRESULT ArchiveId([out. IHold :: ArchiveId This property specifies the ArchiveID of the archive where the item that this hold object refers to is stored. to which this hold is about to be applied.Content Management API IHold :: ArchiveId Table 4-43 IHold properties (continued) Property Description Metadata This read only property returns the metadata that is stored with the hold. [in] BSTR newVal BSTR containing the value of the archive Id where the current item. ConsumerGUID This read only property returns the unique identifier of the calling application that placed the hold. retval] BSTR* pVal Pointer to a BSTR that will contain the archive Id of the archive holding the item referred to by this hold. The property is read/write.Add(hold).ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60". GroupId This read only property returns the identifier of the group of holds to which the hold belongs. hold. 301 . Remarks Being derived from IDispatch. Parameters [out. this interface can be used by scripting languages.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Hold. holds. HRESULT ArchiveId([in] BSTR newVal). ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Item(i + 1). [out] IHolds holds = Item.ArchiveId. Syntax HRESULT ItemId([out. string archId = hold. Return value S_OK Success.Holds. The property is read/write. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. hold. HRESULT ItemId([in] BSTR newVal). hold. . IHold :: ItemId This property specifies the identifier of the item to which the hold object refers.Hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".302 Content Management API IHold :: ItemId Remarks This property must be set before a hold is placed or released. or the value is not a syntactically valid Archive Id.Add(hold). i++) { I Hold hold = (IHold)holds. i < holds. for (int i = 0. Example [in] IHold hold = cmAPI. holds. retval] BSTR* pVal).Count . 303 . CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. i++) { IHold hold = (IHold)holds.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60".Hold.Add(hold). The identifier can be a Saveset Id or a Transaction Id. Example [in] IHold hold = cmAPI.Count . [out] IHolds holds = Item.Content Management API IHold :: ItemId Parameters [out. i < holds. Return value S_OK Success.Holds. holds.ItemId. string itemID = hold. Remarks This property must be set before a hold is placed. or value passed in is not a syntactically valid Saveset Id or Transaction Id. See “Saveset IDs and Transaction IDs” on page 71.Item(i + 1). [in] BSTR newVal BSTR containing the item Id to set for this hold. hold. hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite". retval] BSTR* pVal Pointer to a BSTR that will contain the current item Id held by this hold. for (int i = 0. Hold. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. This property is returned after a hold has been placed. or newVal is not a syntactically valid Hold Id. [in] BSTR newVal BSTR that will contain the new value of the hold Id. retval] BSTR* pVal).ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}". The property is read/write. holds. Remarks The maximum length for this property is 128 characters. Example [in] IHolds holds = cmAPI. Syntax HRESULT Id([out. HRESULT Id([in] BSTR newVal).ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite".Holds. and must be set before a hold can be released. retval] BSTR* pVal Pointer to a BSTR that will contain the current hold Id. hold.304 Content Management API IHold :: Id IHold :: Id This property identifies the hold object. Parameters [out. . IHold hold = cmAPI. Return value S_OK Success. Syntax HRESULT Status([out.Item(i + 1).ReleaseHolds.Add(hold). i < holds. The property is read only. i++) { IHold hold = (IHold)holds.Id.Count . Return value S_OK Success. retval] VARIANT* pVal Pointer to a VARIANT that will contain the current status value.Id = 123. [out] IHolds holds = Item.Holds. string ID = hold. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. //add more holds holds. Parameters [out. Remarks The VARTYPE of the variant must be vt = VT_I4. holds. retval] VARIANT* pVal).Content Management API IHold :: Status hold. 305 . IHold :: Status This property returns the status of the hold after an attempt to either place or release a hold. for (int i = 0. Get method is called and the DetailLevel parameter includes the HoldData bit. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. Syntax HRESULT Metadata([out. i < holds. for (int i = 0.Holds. The property is read only. string metadata = hold. retval] BSTR* pVal Pointer to a BSTR that will contain the metadata for this hold. Parameters [out. Return value S_OK Success.Item(i + 1). IHold :: ConsumerGUID This property returns the unique identifier of the calling application that placed the hold.Count . i++) { IHold hold = (IHold)holds. retval] BSTR* pVal). The property is read only. Remarks This property is only populated when the IItem.306 Content Management API IHold :: Metadata IHold :: Metadata This property returns the metadata that is stored with the hold. .MetaData. Example IHolds holds = Item. See “IItem :: Get” on page 194. retval] BSTR* pVal Pointer to a BSTR that will contain the consumer GUID of the application that placed the hold.Count . 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. i++) { IHold hold = (IHold)holds. Return value S_OK Success.Item(i + 1). i < holds.Content Management API IHold :: GroupId Syntax HRESULT ConsumerGUID([out. retval] BSTR* pVal).ConsumerGUID. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. Example IHolds holds = Item. The property is read only. for (int i = 0. Parameters [out.Holds. or pVal is not a valid GUID. 307 . Syntax HRESULT GroupId([out. IHold :: GroupId This property returns the identifier of the group of holds to which the hold belongs. retval] BSTR* pVal). string conGUID = hold. a zero-based array style indexer.Count . Example IHolds holds = Item. for (int i = 0.Holds. Syntax interface ICollectionBase : IDispatch Member summary Table 4-44 ICollectionBase properties Property Read/Write Description Count Read only Number of items in the collection. string groupID = hold. The interface provides the count of items. a standard COM enumerator interface.308 Content Management API ICollectionBase : IDispatch Parameters [out.GroupId. Remarks See “IHolds :: GroupId” on page 290. retval] BSTR* pVal Pointer to a BSTR that will contain the current group Id. Return value S_OK Success. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL. for example. ICollectionBase : IDispatch The ICollectionBase interface provides common collection functionality for Enterprise Vault API collections. .Item(i + 1). Archives and VaultStores collections. i < holds. i++) { IHold hold = (IHold)holds. and methods to manage the collection. Version information This interface is available in Enterprise Vault 2007 or later. The property is read only. Clear Clear the current collection.retval] long* value). Item Read only Instance of the item at the zero-based index into the collection.Content Management API ICollectionBase :: Count Table 4-44 ICollectionBase properties (continued) Property Read/Write Description _NewEnum Read only Instance of the standard COM enumerator for the collection.retval] long* value Number of items in the collection. Reset Reset the object back to the initial state. 309 . Maximum Read/Write Maximum number of items in the collection. More Read only Whether or not there were more items than Maximum. ICollectionBase :: Count This property returns the current number of items in the collection. Table 4-45 ICollectionBase methods Method Description Get Populate the collection. Parameters [out. Syntax HRESULT Count([out. Return value S_OK Success. for (long i = 0. ICollectionBase :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the collection object. it is automatically used internally when you use the For Each construct in C#. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER enumerator is NULL.Count. Example [C#] archives.Get(). or VBScript.retval] IUnknown** enumerator). The property is read only.Item(i)). CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL. Remarks This property is a standard property used to support enumerating collections.retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object. This property is hidden in Visual Basic Scripting Edition (VBScript). i < archives. i++) { ProcessArchive(archives.310 Content Management API ICollectionBase :: _NewEnum Return value S_OK Success. Parameters [out. Syntax HRESULT _NewEnum([out. . SearchArchive(archive. i++) { IArchive archive = (IArchive)archives. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER item is NULL.Id). [out. Syntax HRESULT Item([in] long index. Return value S_OK Success.Item(i). i < archives.Count.retval] IUnknown** item).Content Management API ICollectionBase :: Item Example [C#] archives.Get().retval] IUnknown** item Reference to an instance of the collection. foreach (IArchive archive in archives) { SearchArchive(archive. for (long i = 0. The property is read only.Id). or index is invalid. ICollectionBase :: Item This property returns an instance of the item at the zero-based index into the collection treated as a virtual array.Get(). [out. Example [C#] archives. Parameters [in] long index Zero-based index. 311 . is 5000. The property is read/write. Syntax HRESULT Maximum([out. Attempting to build large collections may result in poor performance and failures due to lack of resources. . vault stores and archives. [in] long value Required maximum number of items for the collection.retval] long* value Maximum number of items in the collection. Remarks The default value depends on the collection type but the value for both initial collection types. The default value is set to provide reasonable performance together with reasonable resource usage. lack of available memory. The defaults are as follows: ■ Vault stores 5000 ■ Archives 5000 ■ Items 10000 Return value S_OK Success. or value is invalid. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Value is NULL. Parameters [out. HRESULT Maximum([in] long value).312 Content Management API ICollectionBase :: Maximum ICollectionBase :: Maximum This property sets the maximum number of items for the collection. for example.retval] long* value). archives. archives.Maximum = 6000. The property is read only. Return value S_OK Success. Parameters [out.retval] VARIANT_BOOL* value). if (archives.Maximum = 6000. Syntax HRESULT More([out.retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain true. ICollectionBase :: More This property indicates whether there were more items available in the collection than specified by Maximum.More == true) { //do something. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL. Otherwise it will contain false. 313 .Get().Get(). if there are more items in the collection than the Maximum number specified. Example [C#] archives.Content Management API ICollectionBase :: More Example [C#] archives. archives. See “VaultStores object” on page 107. CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The combination of properties used for the collection selection criteria are invalid. The request should be retried later. See “Archives object” on page 119. CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running. See “Items object” on page 164. Example [C#] archives. Return value S_OK Success. if there are insufficient resources the maximum number of records requested should be reduced. Syntax HRESULT Get(void).com". CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request.Permissions = .Computer = ""EV1.314 Content Management API 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. Remarks Any existing collection is cleared prior to attempting to repopulate the collection.acme. i++) { ProcessArchive(archives. Return value S_OK Success. 315 . Count returns zero. ICollectionBase :: Clear This method clears the current collection.Get(). ICollectionBase :: Reset This method resets the collection back to the initial empty state.Content Management API ICollectionBase :: Clear EV_STG_API_PERMISSIONS_TYPE.ArchiveTypes = EV_STG_API_ARCHIVE_TYPE. i < archives. Syntax HRESULT Clear(void).ARCHIVE_TYPE_SHARED. } //now clear archives before doing another get with different filters set archives. for (long i = 0. archives.PERMISSIONS_SEARCH. Remarks Clears all items from the current collection setting it back to the empty state.Count.Item(i)).Get(). Example [C#] archives. archives.Clear(). Reset(). i < archives. Syntax interface IExtendedErrorInfo : IDispatch .316 Content Management API ExtendedErrorInfo object Syntax HRESULT Reset(void).Count.Item(i)). } //now reset archives before doing another get with different filters set archives. Remarks All items are cleared from the current collection. i++) { ProcessArchive(archives. Example [C#] archives. if any. Return value S_OK Success. for (long i = 0. and all selection criteria properties are reset back to their default empty values. 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.Get(). It is provided for additional information only. Read only Remarks The ExtendedErrorInfo object is read-only. the additional information returned by the IExtendedErrorInfo interface shows that the Enterprise Vault server is in Backup Mode: API Error Code: 0x80040302 (Ref: CONTENTMANAGEMENTAPI_E_BUSY) 317 . Description Read only The description for the Content Management API return value. InnerErrorDescription Read only The description for the internal return value. to add to extended logging details. Version information ■ This interface is available from Enterprise Vault 8.0 SP2. Examples In the following example. The inner error can be any Windows or Enterprise Vault COM return value. Source This property is not currently implemented. InnerError Read only The associated internal return value. 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 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. for example.Content Management API ExtendedErrorInfo object Member summary Table 4-46 IExtendedErrorInfo properties Property Read/Write Description Error Read only The Content Management API return value associated with the most recent call to a Content Management API method. CComPtr<IItem> pItem. HRESULT hr = pItem->CopyTo(pDestItem). [C++] CComPtr<IContentManagementAPI4> pCMAPI. if (pExErrInfo != NULL) { HRESULT hrError = S_OK. EV Internal Error Code: 0xC0041B85 (Ref STORAGE_E_VAULTSTORE_INBACKUPMODE) EV Internal Error Description: The Vault Store is currently in Backup Mode. The following example code shows how the ExtendedErrorInfo object is used.318 Content Management API ExtendedErrorInfo object API Error Description: Enterprise Vault is temporarily unable to process the request. or has insufficient resources. CComPtr<IUnknown> pIUnkErrInfo. hrGLE = pCMAPI->get_LastError(&pIUnkErrInfo). if (SUCCEEDED(hrGLE)) { CComQIPtr<IExtendedErrorInfo> pExtErrInfo(pIUnkErrInfo). CComBSTR bsInnerErrorDesc. . HRESULT hrInnerError = S_OK. The server is busy. or is only able to read data due to ongoing backups. Wait a while and then try again. pExErrInfo->get_Error(&hrError). CComBSTR bsErrorDesc. if (FAILED(hr)) { HRESULT hrGLE (S_OK). hrError.InnerErrorDescription Msg = "***************************" & vbCrLf & vbCrLf Msg = Msg & "** CM API EXTENDED ERROR INFO" & vbCrLf & vbCrLf Msg = Msg & " Error Code: 0x" & Hex(vbError) & vbCrLf & vbCrLf Msg = Msg & " Error Description: " & szErrorDesc & vbCrLf & vbCrLf Msg = Msg & " InnerError Code: 0x" & Hex(vbExtError) & vbCrLf & vbCrLf 319 .Content Management API ExtendedErrorInfo object pExErrInfo->get_InnerError(&hrInnerError). pExErrInfo->get_Description(&bsErrorDesc).Clear set oExtErr = ecmAPI. pExErrInfo->get_InnerErrorDescription(&bsInnerErrorDesc).LastError vbError = oExtErr. bsErrorDesc.InnerError szErrorDesc = oExtErr. } } } The following example code shows how the ExtendedErrorInfo object is used. [VBScript] private Sub ReportCMAPIError(byref ecmAPI) dim dim dim dim oExtErr szErrorDesc.Error vbExtError = oExtErr.Description szInnerErrorDesc = oExtErr. bsInnerErrorDesc). szInnerErrorDesc vbError. vbExtError Msg Err. // *** Use error info AddExtendedErrorToLogFile(L"Failed to copy archived item". hrInnerError. This property is read only. Return value S_OK Success. Parameters [out. retval] long* pVal). This property is read only. Syntax HRESULT Error([out.Clear end sub IExtendedErrorInfo :: Error This property provides the Content Management API return value associated with the most recent call to a Content Management API method. Remarks See “Content Management API return values” on page 619. IExtendedErrorInfo :: Description This property provides the error description for the Content Management API return value.320 Content Management API IExtendedErrorInfo :: Error Msg = Msg & " InnerError Description: " & szInnerErrorDesc & vbCrLf & vbCrLf Msg = Msg & "***************************" WScript. E_INVALIDARG pVal is Null. .Echo Msg Err.retval] long* pVal Pointer to a long data type containing the Content Management API return value. Parameters [out. retval] long* pVal). Remarks The error description strings are supplied in English only.retval] long* pVal Pointer to a long data type containing the internal return value. This property is read only. 321 . for example. E_INVALIDARG pVal is Null IExtendedErrorInfo :: InnerError This property provides the internal return value associated with the most recent call to a Content Management API method. Parameters [out. It is provided for additional information only. Syntax HRESULT InnerError([out.retval] BSTR* pVal Pointer to a BSTR containing the error description. Return value S_OK Success. to add to extended logging details. retval] BSTR* pVal). Remarks The inner error can be any Windows or Enterprise Vault COM return value. and it is not guaranteed that the same error scenario will return the same inner error value with future versions of Enterprise Vault. The list of values is not documented.Content Management API IExtendedErrorInfo :: InnerError Syntax HRESULT Description([out. This property is read only. Remarks The error description strings are supplied in English only.retval] BSTR* pVal Pointer to a BSTR containing the error description. E_INVALIDARG pVal is Null IExtendedErrorInfo :: InnerErrorDescription This property provides the error description for the Enterprise Vault internal return value. Return value S_OK Success. This property is read only. Parameters [out. retval] BSTR* pVal). . Syntax HRESULT InnerErrorDescription([out. Syntax HRESULT Source([out.322 Content Management API IExtendedErrorInfo :: InnerErrorDescription Return value S_OK Success. E_INVALIDARG pVal is Null IExtendedErrorInfo :: Source This property provides the GUID of the Content Management API object that was the source of the error information. retval] GUID* pVal). Content Management API DiagnosticsAPI object Parameters [out,retval] GUID* pVal GUID of the Content Management API object. Remarks This property is not currently implemented, and returns E_NOTIMPL. Return value E_NOTIMPL Not implemented. DiagnosticsAPI object 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-47 IDiagnosticsAPI properties Property Read/Write Description Name Read/Write Name of application Table 4-48 IDiagnosticsAPI methods Method Description IsTraceEnabled Test whether trace is enabled for the selected level. LogEvent Creates an entry in the Enterprise Vault event log. Trace Traces a message, if trace enabled for the selected level. 323 324 Content Management API IDiagnosticsAPI : Name Remarks For a description of the Dtrace utility, see the Enterprise Vault Utilities guide. Version information ■ This interface is available from Enterprise Vault 2007. 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 the following: Application: Acme.RM Failed to determine archive. Identity: John Paul Jones Error: Entry Not Found (0x0002) Content Management API IDiagnosticsAPI : IsTraceEnabled Return value S_OK Success. E_POINTER pVal is NULL, or is invalid. E_ACCESSDENIED The property has already been set. 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 76. This method can be used to optimize the cost of building the trace message for the normal case, where trace is not enabled. Return value S_OK Success. E_POINTER enabled is NULL. IDiagnosticsAPI : LogEvent This method creates an entry in the Enterprise Vault event log. 325 326 Content Management API IDiagnosticsAPI : Trace Syntax HRESULT LogEvent([in] EV_API_EVENT_TYPE eventType, [in] BSTR message); Parameters [in] EV_API_EVENT_TYPE eventType EV_API_EVENT_TYPE value. [in] BSTR message Message to write. Remarks EV_API_EVENT_TYPE is an enumerated value that indicates the type of event. See “EV_API_EVENT_TYPE enumeration” on page 76. The events are logged under a single Event Id, 7002. The event source is set to Enterprise Vault and the event category is determined by the executable logging the event. If the executable is not an Enterprise Vault executable then the category is None. Return value S_OK Success. E_INVALIDARG eventType is invalid or message is NULL. 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. Content Management API IDiagnosticsAPI : Trace Remarks EV_API_TRACE_LEVEL is an enumerated value that indicates the trace level. See “EV_API_TRACE_LEVEL enumeration” on page 76. In the trace output, the application name is enclosed in brackets and prefixed to the trace message content to enable filtering in the DTrace utility. For example with Name set to the value Acme.RM, the message "Initialization complete" would appear as: 4553 10:42:04.101 [5016] (AcmeRMServer) <4342> EV:L [Acme.RM] Initialization complete Trace messages are captured dynamically by the Enterprise Vault DTrace utility if the component (that is, the executable) is enabled for tracing within the utility. The DTrace monitoring level setting for the component determines whether or not the Trace method generates a trace entry and hence whether or not the trace message is captured by the DTrace utility as shown in the table below. Table 4-49 DTrace setting Mapping of API trace levels to Dtrace monitoring level settings TRACE_LEVEL_HIGH TRACE_LEVEL_MEDIUM TRACE_LEVEL_LOW Off No No No Brief Yes No No Medium Yes Yes No Verbose Yes Yes Yes The standard coding advice for tracing is to use TRACE_LEVEL_MEDIUM by default, use TRACE_LEVEL_HIGH to provide a high level view of the application progress, and reserve use of TRACE_LEVEL_LOW for situations requiring low-level debugging. Return value S_OK Success. E_INVALIDARG message is NULL. 327 328 Content Management API IDiagnosticsAPI : Trace Chapter 5 NSF Manager API This chapter includes the following topics: ■ About NSF Manager API ■ NSF Manager API ■ Enumerations ■ NSFManager object ■ INSFManager :: OpenNSF ■ INSFManager :: CreateNSF ■ INSFManager :: CloseNSF ■ INSFManager :: ViewNote ■ INSFManager :: ImportNote ■ INSFManager :: ExportNote ■ INSFManager :: DeleteNote ■ INSFManager :: InitializeNotes ■ INSFManager :: TerminateNotes ■ INSFManager :: SwitchToID About NSF Manager API This chapter describes the Enterprise Vault NSF Manager API, and its interface and methods. 330 NSF Manager API NSF Manager API NSF Manager API The NSF Manager API interacts with the Content Management API to enable items in Notes databases to be stored in, or retrieved from, Enterprise Vault archives. NSF Manager API creates and uses an NSF database file to hold data being passed to, or received from, the Content Management API. How Enterprise Vault processes Lotus Notes messages is described in an appendix to this guide. See “About storing and retrieving message items” on page 627. 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). See “IContent :: Data” on page 220. ■ IContent::FileExtension defines the type of the item ("dvns" or IContent.MIMEFormat = "application/x-evnotestream"). See “IContent :: FileExtension” on page 215. and See “IContent :: MIMEFormat” on page 217. ■ IItem::ArchiveId determines the destination archive for the item. See “IItem :: ArchiveId” on page 174. ■ IItem::Insert stores the item in the archive. See “IItem :: Insert” on page 191. ■ Use DeleteNote to delete the note from the NSF database (optional). ■ Use CloseNSF to release the open NSF database. ■ Use TerminateNotes to terminate the NSF Manager API. NSF Manager API NSF Manager API The following steps outline how an application can use the NSF Manager and Content Management API to retrieve a Note from an archive and view it in the Notes client: ■ Use InitializeNotes to initialize the API. ■ Use SwitchToID to set the Notes security context (optional). ■ Use OpenNSF or CreateNSF to open or create an NSF database to hold the item to be retrieved and viewed. ■ Use ImportNote to import the item from Content Management API to the NSF database. The following Content Management API properties and method can be used to retrieve the item from the archive: ■ IItem::ArchiveId defines the archive where the item is stored. See “IItem :: ArchiveId” on page 174. ■ IItem::Get retrieves the item from the archive. See “IItem :: Get” on page 194. ■ IContent::Data holds the item content (as a file, or an IStream or ILockBytes object). See “IContent :: Data” on page 220. ■ IContent::FileExtension specifies the type of the item ("dvns" or IContent::MIMEFormat = "application/x-evnotestream"). See “IContent :: FileExtension” on page 215. and See “IContent :: MIMEFormat” on page 217. ■ Use ViewNote to open the item in the Notes client. ■ Use DeleteNote to delete the item from the NSF database (optional). ■ Use CloseNSF to release the open NSF database. ■ Use TerminateNotes to terminate the NSF Manager API. Components The NSF Manager API contains one apartment-threaded, automation-friendly COM class: ■ NSFManager Security When you interact with databases on a server, you must use an ID file that has appropriate permissions. 331 332 NSF Manager API Enumerations Enumerations This section describes enumerations used by the NSF Manager API. InitializeNotes enumeration InitializeNotes is an enumerated value that is used in conjunction with the InitializeNotes and TerminateNotes methods: enum EV_NOTES_INIT_MODE { EV_NOTES_INIT_APPLICATION, EV_NOTES_INIT_THREAD }; NSFManager object The NSFManager object implements the following interface: ■ INSFManager Syntax interface NSFManager : IDispatch Member summary Table 5-1 Member summary Method Description OpenNSF Opens an existing database. CreateNSF Creates a new database. CloseNSF Closes the open database and optionally deletes it. ViewNote Launches the Notes client and opens the specified note. ImportNote Imports a note from a file, or an IStream or ILockBytes object. ExportNote Exports a note to a file, or an IStream or ILockBytes object. DeleteNote Deletes the specified note. InitializeNotes Initializes the Notes runtime on the main application thread, or on a worker thread. NSF Manager API INSFManager :: OpenNSF Table 5-1 Member summary (continued) Method Description TerminateNotes Terminates the Notes runtime on the main application thread, or on a worker thread. SwitchToID Switches to the specified ID file. Requirements See “Programming notes” on page 56. CLSID FBD0FA42-EF3C-4761-B3E4-9C39422273CE Prog ID KVS.EnterpriseVault.LotusDomino.NSFManager Type Library EVContentManagementAPILib DLL KVS.EnterpriseVault.NSFManager.dll .NET Primary Interop Assembly (PIA) KVS.EnterpriseVault.Interop.EVContentManagementAPI.dll .NET PIA namespace KVS.EnterpriseVault.Interop 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. 333 334 NSF Manager API INSFManager :: CreateNSF 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); } 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. NSF Manager API INSFManager :: CloseNSF 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); } 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. 335 InitializeNotes( EV_NOTES_INIT_MODE. which must exist in the database. Return value S_OK (success) or standard COM error codes.OpenNSF(@"c:\DBs\TestDB. nsfMgr. } finally { nsfMgr. nsfMgr. INSFManager nsfMgr = (INSFManager)Activator.EV_NOTES_INIT_APPLICATION).LotusDomino.CreateInstance(type).EnterpriseVault.EV_NOTES_INIT_APPLICATION). without deleting it: Type type = Type. } INSFManager :: ViewNote This method launches the Notes client and opens the specified note.CloseNSF(false).nsf"). Parameters [in] ULONG ulNoteId The ID of the note. Syntax HRESULT ViewNote([in] ULONG ulNoteId). try { nsfMgr.GetTypeFromProgID( "KVS.NSFManager"). Example The following example how to use ViewNote to open a note: .336 NSF Manager API INSFManager :: ViewNote Example The following example shows how to use CloseNSF to close a database.TerminateNotes( EV_NOTES_INIT_MODE. LotusDomino.EnterpriseVault.OpenNSF(@"c:\DBs\TestDB. nsfMgr. or an IStream or ILockBytes object. uint noteId = nsfMgr. nsfMgr.NSF Manager API INSFManager :: ImportNote Type type = Type.TerminateNotes( EV_NOTES_INIT_MODE. retval] ULONG *pulNoteId Returns the ID of the imported note. nsfMgr. [out.CloseNSF(false). } finally { nsfMgr. 337 .EV_NOTES_INIT_APPLICATION). } INSFManager :: ImportNote This method imports a note from a file. try { nsfMgr. Syntax HRESULT ImportNote( [in] VARIANT vInputNote. as returned from the Content Management API or by the ExportNote method.ViewNote(noteId).ImportNote(@"c:\EVNotes\storedNote. retval] ULONG *pulNoteId). Parameters [in] VARIANT vInputNote Variant that contains the data to be imported.CreateInstance(type).GetTypeFromProgID( "KVS.EV_NOTES_INIT_APPLICATION).NSFManager").dvns"). INSFManager nsfMgr = (INSFManager)Activator. [out.InitializeNotes( EV_NOTES_INIT_MODE. Return value S_OK (success) or standard COM error codes. The note to be imported is in the proprietary Enterprise Vault format.nsf"). dvns").ImportNote(@"c:\EVNotes\storedNote. try { nsfMgr. [in] VARIANT vOutputNote).nsf"). } INSFManager :: ExportNote This method exports a note from the NSF database to a file. nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.CreateInstance(type). or an IStream or ILockBytes object. The note exported is in proprietary Enterprise Vault format.GetTypeFromProgID( "KVS.338 NSF Manager API INSFManager :: ExportNote Example The following example how to use ImportNote to import a note: Type type = Type.ViewNote(noteId).EV_NOTES_INIT_APPLICATION).CloseNSF(false). nsfMgr. .LotusDomino. and can be passed to the Content Management API or ImportNote method. uint noteId = nsfMgr.NSFManager").OpenNSF(@"c:\DBs\TestDB.EV_NOTES_INIT_APPLICATION). Parameters [in]_ULONG_ulNoteId The ID of the note. nsfMgr. INSFManager nsfMgr = (INSFManager)Activator. Syntax HRESULT ExportNote( [in] ULONG lNoteId. } finally { nsfMgr. [in] VARIANT vOutputNote A variant that contains the exported data.TerminateNotes( EV_NOTES_INIT_MODE.EnterpriseVault. NSFManager"). nsfMgr. @"c:\EVNotes\storedNote.nsf"). Parameters [in] ULONG ulNoteId The ID of the note. Example The following example shows how to use ExportNote to export a note: Type type = Type.NSF Manager API INSFManager :: DeleteNote Return value S_OK (success) or standard COM error codes.EV_NOTES_INIT_APPLICATION).ExportNote(0x8f6.OpenNSF(@"c:\DBs\TestDB.GetTypeFromProgID( "KVS. try { nsfMgr. INSFManager nsfMgr = (INSFManager)Activator. Syntax HRESULT DeleteNote([in] ULONG ulNoteId).TerminateNotes( EV_NOTES_INIT_MODE.dvns"). } INSFManager :: DeleteNote This method deletes the note from the NSF database.CloseNSF(false). nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE. } finally { nsfMgr.EV_NOTES_INIT_APPLICATION). nsfMgr. 339 .LotusDomino.CreateInstance(type).EnterpriseVault. Return value S_OK (success) or standard COM error codes. 340 NSF Manager API INSFManager :: InitializeNotes Example The following example shows how to use DeleteNote to delete a note: Type type = Type.nsf").CloseNSF(false).DeleteNote(0x8a6).EnterpriseVault.InitializeNotes( EV_NOTES_INIT_MODE. nsfMgr. } INSFManager :: InitializeNotes This method initializes the Notes runtime on the main application thread.NSFManager").EV_NOTES_INIT_APPLICATION).LotusDomino. INSFManager nsfMgr = (INSFManager)Activator. nsfMgr. nsfMgr. The main thread must initialize Notes before any worker threads.OpenNSF(@"c:\DBs\TestDB. Syntax HRESULT InitializeNotes([in] EV_NOTES_INIT_MODE initMode). indicating whether to initialize on the main application thread or a worker thread.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION). or on a worker thread. Return value S_OK (success) or standard COM error codes. .GetTypeFromProgID( "KVS. try { nsfMgr.CreateInstance(type). } finally { nsfMgr. Parameters [in] EV_NOTES_INIT_MODE initMode Value of the enum. nsfMgr.GetTypeFromProgID( "KVS.CreateNSF( @"c:\Program Files\Lotus\Notes\Data\mail8.TerminateNotes( EV_NOTES_INIT_MODE. Terminate the Notes runtime on the worker threads before the main thread. @"c:\DBs\TestDB.EV_NOTES_INIT_APPLICATION).EV_NOTES_INIT_APPLICATION). 341 .CloseNSF(false).LotusDomino. } finally { nsfMgr. Return value S_OK (success) or standard COM error codes. try { nsfMgr.CreateInstance(type).nsf"). } INSFManager :: TerminateNotes This method terminates the Notes runtime on the main application thread. Parameters [in] EV_NOTES_INIT_MODE initMode Value of the enum.NSFManager"). INSFManager nsfMgr = (INSFManager)Activator.InitializeNotes( EV_NOTES_INIT_MODE. Syntax HRESULT TerminateNotes([in] EV_NOTES_INIT_MODE initMode). or on a worker thread. indicating whether to terminate on the main application thread or a worker thread. nsfMgr.NSF Manager API INSFManager :: TerminateNotes Example The following example shows how to use InitializeNotes to initialize the Notes runtime on the main application thread: Type type = Type.EnterpriseVault.ntf". } finally { nsfMgr.nsf"). nsfMgr. Syntax HRESULT SwitchToID( [in] BSTR bsIdFilePath. which is required when you create an NSF database from a template. Return value S_OK (success) or standard COM error codes.GetTypeFromProgID( "KVS. [in] BSTR bsPassword).EV_NOTES_INIT_APPLICATION). or open an NSF database from a remote server.342 NSF Manager API INSFManager :: SwitchToID Example The following example shows how to use TerminateNotes to terminate the Notes runtime: Type type = Type. try { nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.LotusDomino.CreateInstance(type).CloseNSF(false). .InitializeNotes( EV_NOTES_INIT_MODE.OpenNSF(@"c:\DBs\TestDB.EnterpriseVault.EV_NOTES_INIT_APPLICATION). Parameters [in] BSTR bsIdFilePath The full path and file name of the ID file. INSFManager nsfMgr = (INSFManager)Activator. } INSFManager :: SwitchToID This method switches to the specified ID file. nsfMgr.NSFManager"). [in] BSTR bsPassword The ID file's password. CloseNSF(false). try { nsfMgr. nsfMgr. } finally { nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.NSF Manager API INSFManager :: SwitchToID Example The following example shows how to use SwitchToID to switch to a specified ID: Type type = Type.EV_NOTES_INIT_APPLICATION).CreateInstance(type). } 343 . nsfMgr. @"passw0rd").LotusDomino.NSFManager").id".SwitchToID( @"c:\Program Files\Lotus\Notes\Data\IDs\user. INSFManager nsfMgr = (INSFManager)Activator.EnterpriseVault.InitializeNotes( EV_NOTES_INIT_MODE.OpenNSF(@"DomSvr1/ACME!!mail\user.GetTypeFromProgID( "KVS. nsfMgr.nsf").EV_NOTES_INIT_APPLICATION). 344 NSF Manager API INSFManager :: SwitchToID . Chapter Filtering APIs This chapter includes the following topics: ■ About the Filtering APIs ■ Exchange Filtering API ■ Enumerations (Exchange filtering) ■ IExternalFilter interface ■ IExternalFilter :: Initialize ■ IExternalFilter :: ProcessFilter ■ IExternalFilter :: FilteringComplete ■ IArchivingControl interface for Exchange filtering ■ IArchivingControl :: currentVaultId ■ IArchivingControl :: currentRetentionCategoryId ■ IArchivingControl :: defaultRetentionCategoryId ■ IArchivingControl :: deleteOriginalItem ■ IArchivingControl :: createShortcutToItem ■ IArchivingControl :: Action ■ IArchivingControl :: MAPISession ■ IArchivingControl :: MAPIMessage ■ IArchivingControl :: AddIndexedProperty ■ IArchivingControl :: IndexedPropertiesSet 6 . 346 Filtering APIs ■ IArchivingControl :: AddIndexPropertyToSet ■ IArchivingControl :: AddIndexPropertySet ■ IArchivingControl :: TransactionID ■ IArchivingControl :: AgentType ■ IArchivingControl :: AgentAssignedRetentionCategoryId ■ IArchivingControl :: AgentAssignedVaultId ■ IArchivingControl :: GetFilterProperty ■ IArchivingControl :: PutFilterProperty ■ IArchivingControl :: AttachmentAction ■ IArchivingControl :: RetryStatus ■ IArchivingControl :: ReArchiveStatus ■ IArchivingControl2 :: BrowserViewURL ■ IArchivingControl2 :: NativeItemURL ■ IArchivingControl2 :: MessageClass ■ IArchivingControl2 :: MAPISaveChanges ■ IArchivingControl3 :: SenderRecipientXML ■ IArchivingControl3 :: EnvelopeSenderRecipientXML ■ IArchivingControl3 :: MessageDirection ■ IArchivingControl4 :: AddIndexedPropertyEx ■ Domino Filtering and File System Filtering APIs ■ Enumerations (Domino filtering) ■ Enumerations (File System Filtering) ■ IExternalFilter interface ■ IExternalFilter :: Initialize ■ IExternalFilter :: ProcessFilter ■ IExternalFilter :: FilteringComplete ■ IExternalFilter :: Shutdown . Filtering APIs ■ IArchivingControl interface ■ IArchivingControl :: OriginalVaultID ■ IArchivingControl :: CurrentVaultID ■ IArchivingControl :: OriginalRetentionCategoryID ■ IArchivingControl :: CurrentRetentionCategoryID ■ IArchivingControl :: IndexData ■ IArchivingControl :: FilterProperties ■ ILotusArchivingControl interface ■ ILotusArchivingControl :: Action ■ ILotusArchivingControl :: NoteHandle ■ ILotusArchivingControl :: DatabaseHandle ■ ILotusArchivingControl :: DatabaseName ■ ILotusArchivingControl :: SenderRecipientXML ■ ILotusArchivingControl :: StoreIdentifier ■ ILotusArchivingControl :: Direction ■ IFileArchivingControl interface ■ IFileArchivingControl :: Action ■ IFileArchivingControl :: Name ■ IFileArchivingControl :: Attributes ■ IFileArchivingControl :: CreationTimeUtc ■ IFileArchivingControl :: LastAccessTimeUtc ■ IFileArchivingControl :: LastWriteTimeUtc ■ IFileArchivingControl :: GetAccessControl ■ IFileArchivingControl :: SetAccessControl ■ IFileArchivingControl :: Length ■ IFileArchivingControl :: Open ■ IFileArchivingControl :: StreamNames 347 . Items may be selected using attributes such as .348 Filtering APIs About the Filtering APIs ■ IFileArchivingControl :: OpenStream ■ IFileArchivingControl :: DeleteStream ■ IFileArchivingControl :: ExtendedAttributes ■ IIndexMetadata interface ■ IIndexMetadata :: ToXML ■ IIndexMetadata :: FromXML ■ IIndexMetadata :: Add ■ IIndexMetadata :: Clear ■ IIndexMetadata :: Count ■ IIndexMetadata :: DateTimesUTC ■ IIndexProperty interface ■ IIndexProperty :: Set ■ IIndexProperty :: Name ■ IIndexProperty :: Value ■ IIndexProperty :: Searchable ■ IIndexProperty :: Retrievable ■ IKeyedList interface ■ IKeyedList :: Insert ■ IKeyedList :: RemoveAt About the 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 ■ File System Filtering API Filtering involves selecting specific items according to set criteria. and performing certain actions on those items. you may want to collect statistics on particular item types. archiving the item with a specific retention category.NET interfaces. Enterprise Vault includes generic filters for Exchange Server archiving and Domino Server archiving. For example. and instructions on how to configure the generic Enterprise Vault filters. or storing the item in a particular archive. subject. you do not require access to the Enterprise Vault API. or a combination of attributes. You can configure multiple filters for a particular type of archiving. 349 . The Domino Filtering API can be used to develop proprietary filters for Domino Journaling tasks. In the filter you can use the Content Management DiagnosticsAPI class to add tracing and event logging. For an overview of filtering. see the "Configuring custom filtering" section in the following manuals: Setting Up Exchange Server Archiving Setting Up Domino Server Archiving No generic filter is currently provided for file system filtering. for example. 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. message recipients. If you want to implement File System Filtering then you must create a filter using the File System Filtering API. is presented as a set of COM interfaces. This API can be used to develop proprietary filters for the following archiving tasks: ■ Exchange Mailbox task ■ Exchange Journaling task ■ Exchange Public Folder task Both the Domino Filtering API and the File System Filtering API are presented as a set of . 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. See “DiagnosticsAPI object” on page 323. To use these generic filters. classify items based on metadata or content. The Exchange Filtering API. or removing attachments. the associated archiving task will process these in order. The File System Filtering API can be used to develop proprietary filters for File System Archiving tasks. or add proprietary information to items as they are archived. You enable filtering by configuring registry settings for the associated archiving task.Filtering APIs About the Filtering APIs author. Other actions could include deleting the item. Actions could include. exe. and called on a per-message basis during the archiving process. ■ Restart the associated archiving tasks.350 Filtering APIs Exchange Filtering API ■ Configure the appropriate filtering registry settings for the archiving tasks that you want to perform filtering. For Domino filtering. Exchange Filtering API The Exchange Filtering API provides a mechanism for COM components to be loaded by the appropriate Exchange archiving task.config.config. See “File System filtering registry settings” on page 395.NET application configuration file is EvFSAArchivingTask. ■ See “Domino Filtering and File System Filtering APIs” on page 389. . See “Domino filtering registry settings” on page 394. The registry settings enable filtering for the archiving task and define the external filters to process.NET application configuration file is EVLotusDominoJournalTask. the . the . you must update binding redirections in the associated . After you upgrade Enterprise Vault.exe. Details of the filtering APIs are given in the following sections: ■ See “Exchange Filtering API” on page 350. For File System filtering. See “Updating binding redirections in configuration files” on page 54. Details of the registry settings are given in the following sections: See “Exchange filtering registry settings” on page 352.NET application configuration files to use the newer version of the Enterprise Vault API runtime. ■ The filter processes the message synchronously. illustrates how Enterprise Vault implements Exchange external filters: ■ If the registry settings are configured to enable filtering for the Exchange Mailbox. the task calls the task filter controller when processing a message. to retrieve information about the message. using the methods and properties of the IArchivingControl4 interface to set properties that define how the Exchange archiving task is to process the message. ■ The external filter calls the IArchivingControl4 interface. ■ Provided the stopFiltering parameter is not set to TRUE. which implements the IExternalFilter interface. Figure 6-1. each filter is applied in turn to the message. ■ The task filter controller invokes the first external filter.Filtering APIs Exchange Filtering API Figure 6-1 Overview of Exchange filtering Enterprise Vault Server Modified contents Enterprise Vault Exchange Journaling task Enterprise Vault Exchange Mailbox task Vault store Enterprise Vault Exchange Public Folder task External filter 1 External filter 1 ProcessFilter() Modified contents Task Filter Controller External filter 1 The figure. 351 . which is implemented by the task filter controller. Journaling or Public Folder tasks. as modified by the external filters and also taking account of any archiving actions set by the external filters. This enables the filter to tidy up and release any resources used while processing the message. 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. A filter should be implemented as an apartment-threaded. and Public Folder tasks is enabled using registry settings under the following registry key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering You add a new key to specify the type of archiving task that is to perform the filtering.352 Filtering APIs Exchange Filtering API ■ After the message has been processed by all of the registered filters. you need to obtain and install the appropriate Enterprise Vault archiving license. ■ The Exchange archiving task then completes archiving the message. This is because the Enterprise Vault Exchange archiving tasks are written in an unmanaged language and Microsoft has not implemented a managed (. the task filter controller then invokes the FilteringComplete method for each filter. Developing Exchange external filters Note: External filters for Exchange filtering must be developed in unmanaged code. Journaling. The key can be one of the following: ■ Mailbox ■ Journaling ■ PublicFolder .NET) MAPI library. Exchange filtering registry settings Filtering for Enterprise Vault Exchange Mailbox. 1 = s 'SampleFilterClass Class' { 353 . filter 1 is applied and then filter 2.ClassName) of the COM class implementing IExternalFilter for this particular filter. For the value of each filter entry give the ProgID (ProjectName.SampleFilterClass. as defined in the external filter class registration (.Filter3 In this case. if the Compliance Accelerator Journaling Connector filter exists. If one number is missing. the filter names should form an unbroken numerical sequence. For the name of each filter entry. it must be last in the sequence. 3 and so on. Note: When configuring filtering for Exchange journaling tasks. For example: HKCR { EV10FilterVersion. The following example shows three external filters that have been configured for the Exchange Mailbox archiving tasks. The filters are applied in numerical order. use the values. to add filtering for the Exchange Mailbox archiving tasks.Filter1 2 = ACompany.rgs) file. filter processing stops after filter 2 because the filter name sequence is broken. HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox 1 = ACompany. 2.Filter2 4 = ACompany. no further filters are applied. If there are multiple filters. However. you add the Mailbox key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox You then add a string value to the Mailbox key for each of the required external filters. 1.Filtering APIs Exchange Filtering API For example. 1' VersionIndependentProgID = s 'EV10FilterVersion.1 The following optional DWORD values can also be created to control filtering: ■ Override — This setting has the following effect: ■ Exchange Journaling tasks.SampleFilterClass.354 Filtering APIs Exchange Filtering API CLSID = s '{B5FFF252-D74C-4723-B812-41E15B4C57EF}' } EV10FilterVersion. this setting forces the Exchange Journaling tasks to retry messages that were marked as MARK_DO_NOT_ARCHIVE by a previous filter. . If created under the Journaling key.1' } NoRemove CLSID { ForceRemove {B5FFF252-D74C-4723-B812-41E15B4C57EF} = s 'SampleFilterClass Class' { ProgID = s 'EV10FilterVersion.SampleFilterClass' ForceRemove 'Programmable' InprocServer32 = s '%MODULE%' { val ThreadingModel = s 'Apartment' } val AppID = s '%APPID%' 'TypeLib' = s '{24798ABC-A921-462a-9964-536E8C37E0A3}' } } } In the above example.SampleFilterClass.SampleFilterClass.SampleFilterClass = s 'SampleFilterClass Class' { CLSID = s '{B5FFF252-D74C-4723-B812-41E15B4C57EF}' CurVer = s 'EV10FilterVersion. 1. you would use the following value in the filter registry setting: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox 1 = EV10FilterVersion. and given the value. 1. This folder is created automatically if it does not exist. the task moves the associated messages to the folder. If created under the Maibox or PublicFolder keys. If this setting has the value 1. and given the value. restart the associated archiving tasks to implement the changes. MoveOnFilterFailure — This can be set for Exchange Journaling tasks or Exchange Mailbox tasks. or the setting does not exist. the message involved is moved to the folder. When an unhandled error occurs in the external filter.Filter1 2 = ACompany.Filtering APIs Exchange Filtering API If the value is 0.Filter2 Override = 0 MoveOnFilterFailure = 1 If you make changes to the custom filtering registry settings. the Exchange Journaling tasks do not retry messages that are marked as MARK_DO_NOT_ARCHIVE. or the setting does not exist. If the value is 0. If the value is 0. ■ Exchange Mailbox task. and an unhandled error occurs in the external filter. see the Configuring custom filtering chapter in the the manual. The task tries to process the messages during each archiving run In the following example. 355 . the archiving tasks take the following action: ■ Exchange Journaling task. ■ ■ Exchange Mailbox and Public Folder tasks. this setting turns off custom filtering. For further details of the filtering registry settings. the archiving task does not move the associated messages. Enterprise Vault Journaling Service\Invalid Journal Report in the journal mailbox. the Override and MoveOnFilterFailure settings have been created under the Mailbox registry key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox 1 = ACompany. Setting Up Exchange Server Archiving. When an unhandled error occurs in the external filter. the archiving tasks implement the configured custom filters. Failed external filter. or the setting does not exist. . Enumerations (Exchange filtering) This section lists the enumerations for the Exchange Filtering API. The following Dtrace filter options are useful for verifying that external filtering is working as expected. HARD_DELETE = 4. EV_ACTION enumeration The following enumeration values are defined for EV_ACTION: enum EV_ACTION { NO_ACTION = 0. EV_ATTACHMENT_ACTION enumeration The following enumeration values are defined for EV_ATTACHMENT_ACTION: enum EV_ATTACHMENT_ACTION { NO_ATTACHMENT_ACTION = 0.(? for help) DT Filter>v Current Filter Settings: Include strings: ExternalFiltering EVFilterController For a description of the Dtrace utility.. The default value is ARCHIVE_ITEM. DELETE_ATTACHMENT = 1. MARK_DO_NOT_ARCHIVE = 2. . ARCHIVE_ITEM = 1. and for diagnosing problems: DT>f Manage trace entry filter.356 Filtering APIs Enumerations (Exchange filtering) You can use Dtrace to trace the Enterprise Vault archiving task that is enabled for external filtering. When the task is running in report mode the action is ignored. see the Enterprise Vault Utilities guide. REQUEST_SHUTDOWN = 5 }. MOVE_DELETED_ITEMS = 3.. For example. you may want to localize the descriptive text. users will see a file called Deleted Attachments. If the attachment action is to replace attachments. you can modify the text of this file. If required. it indicates that the task could not determine if the status was a retry. IS_A_RETRY = 2 }. Filters should interpret an UNKNOWN_IF_RETRY status as IS_NOT_RETRY. For example.txt attached to messages that have had attachments deleted by the filter. it contains a list of the names of files that have been deleted. IS_A_REARCHIVE = 2 }.txt. EV_RETRY_STATUS enumeration The following enumeration values are defined for EV_RETRY_STATUS: enum EV_RETRY_STATUS { UNKNOWN_IF_RETRY = 0. this may be returned if the archiving task does not support detecting retries. UNKNOWN_IF_REARCHIVE does not indicate an error. For example. C:\Program Files\Enterprise Vault). in the Enterprise Vault program folder (typically. When they open this file. this may be returned if the archiving task does not support detecting re-archives. The contents of this file are taken from the file. IS_NOT_REARCHIVE = 1. Filters should interpret an UNKNOWN_IF_REARCHIVE status as IS_NOT_REARCHIVE. CF_Replace_Attachment. UNKNOWN_IF_RETRY does not indicate an error. EV_REARCHIVE_STATUS enumeration The following enumeration values are defined for EV_REARCHIVE_STATUS: enum EV_REARCHIVE_STATUS { UNKNOWN_IF_REARCHIVE = 0. 357 . IS_NOT_RETRY = 1.Filtering APIs Enumerations (Exchange filtering) REPLACE_ATTACHMENT = 2 }. it indicates that the task could not determine if the status was a re-archive. IExternalFilter. which is called by the task filter controller. even if they return only S_OK. The ProcessFilter method is where you process the message to your requirements. If the filter makes changes to the message.358 Filtering APIs IExternalFilter interface Message direction enumeration The following enumeration values are defined for MSG_DIRECTION: public enum MSG_DIRECTION { DIRECTION_UNDEFINED = 0. All methods must be implemented. DIRECTION_INTERNAL = 1. ProcessFilter This method is called per-message during the archiving process. DIRECTION_EXTERNAL_OUT = 3 } IExternalFilter interface An external filter implements the following interface: ■ IExternalFilter Syntax interface IExternalFilter : IDispatch Member summary Table 6-1 Member summary Method Description Initialize This method is called during Exchange archiving task initialization. DIRECTION_EXTERNAL_IN = 2. and the changes are to be reflected in the Exchange Server store or the Enterprise Vault archive or both. FilteringComplete This method is called after all filters have been processed for the current item. Remarks The external filter must implement the COM interface. then call the IArchivingControl2 :: MAPISaveChanges method at the end of the 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 IExternalFilter :: Initialize (ProcessFilter or FilteringComplete) that made the changes to the message. IExternalFilter :: ProcessFilter This method is called per-message during the archiving process. Parameters [in] IDispatch *pArchivingControl Reference to the IArchvingControl interface. Making a change to the message in ProcessFilter and delaying the MAPISaveChanges call to FilteringComplete is not regarded as good practice. Parameters [out. retval] VARIANT_BOOL *bStopFiltering Value of true stops the filter controller from processing any more filters on the current item. Syntax HRESULT Initialize([in] IDispatch *pArchivingControl). 359 . The filter should perform any necessary initialization before message processing begins. Syntax HRESULT ProcessFilter([out. The ProcessFilter method is where you process the message to your requirements. retval] VARIANT_BOOL *bStopFiltering). Remarks Filters are instantiated at task startup and released at task shutdown. The interface does not define a corresponding "Uninitialize" method. IExternalFilter :: Initialize This method is called during Exchange archiving task initialization. Syntax HRESULT FilteringComplete(). To find or change the current action to be taken on the message. ■ See “IArchivingControl :: currentVaultId” on page 365. the properties on the IArchivingControl interface are read-only. Remarks After processing has been completed. Similarly to change the retention category or archive for the item. The properties can still be examined so that the filter can determine the final state of the item. IExternalFilter :: FilteringComplete This method is called after all filters have been processed for the current item. it must use appropriate concurrency protection.360 Filtering APIs IExternalFilter :: FilteringComplete Remarks To get a reference to the message. use the currentRetentionCategoryId and currentVaultId properties on the IArchivingControl interface. such as memory or object handles. The external filter must be written to handle concurrent calls. See also ■ See “IArchivingControl :: MAPIMessage” on page 369. IArchivingControl interface for Exchange filtering The task filter controller implements the following interfaces: ■ IArchivingControl ■ IArchivingControl2 . ■ See “IArchivingControl :: Action” on page 368. ■ See “IArchivingControl :: currentRetentionCategoryId” on page 365. use the IArchivingControl :: Action property. If the filter accesses a shared resource. use the IArchivingControl :: MAPIMessage property. It can be used to clean up item-specific resources. integer and date custom index property values. ■ Ability to open an archived item from a URL.Filtering APIs IArchivingControl interface for Exchange filtering ■ IArchivingControl3 ■ IArchivingControl4 The IArchivingControl interface enables an external filter to retrieve and modify properties on the current message. The IArchivingControl2 interface extends the IArchivingControl interface and adds methods and properties to provide the following functionality: ■ Improved handling of MAPI Message Classes. Syntax interface IArchivingControl : IDispatch interface IArchivingControl2 : IArchivingControl interface IArchivingControl3 : IArchivingControl2 interface IArchivingControl4 : IArchivingControl3 Member summary Table 6-2 IArchivingControl properties Property Read/Write Description currentVaultId Read/Write The Id of the archive associated with the current item. This enables searching on date-based selection criteria. The IArchivingControl4 interface extends the IArchivingControl3 interface and adds a new method that accepts a VARIANT data structure when specifying string. currentRetentionCategoryId Read/Write The Id of the retention category associated with the current item. ■ Method for persisting changes made to messages by external filters. The IArchivingControl3 interface extends theIArchivingControl2 interface and adds properties to retrieve sender and recipient information as XML. so that the changes are reflected in the Exchange Server store and the Enterprise Vault archive. 361 . . deleteOriginalItem Read/Write Whether the item is to be deleted from the original location after it has been archived. AgentAssignedRetentionCategoryId Read only Identifies the original retention category assigned. RetryStatus Read only Indicates if current archiving action is a retry.362 Filtering APIs IArchivingControl interface for Exchange filtering Table 6-2 IArchivingControl properties (continued) Property Read/Write Description defaultRetentionCategoryId Read only The Id of the default retention category for the Enterprise Vault Site. AttachmentAction Read/Write Defines action to be taken when processing message attachments. AgentAssignedVaultId Read only Identifies the original destination archive. AgentType Read only Identifies the type of archiving task using the filter. createShortcutToItem Read/Write Whether a shortcut is created in the original location after the item has been archived. IndexedPropertiesSet Read only Lists the properties that have been added using AddIndexedProperty. TransactionID Read only Identifies archiving action. Action Read/Write The action to be taken by the archiving task when the filtering process is complete. MAPIMessage Read only A pointer to the current MAPI message. MAPISession Read only Gets a MAPI session. The custom index property value is specified as a string. and may not be supported in a future release. This method is deprecated. Table 6-4 IArchivingControl methods Method Description AddIndexedProperty Adds metadata to the item. The metadata will be indexed. NativeItemURL Read only Provides a URL that can be use to fetch the original item. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties. 363 . MessageClass Read only Identifies the original value of the MAPI Message Class property. This method is deprecated. Table 6-3 IArchivingControl2 properties Property Read/Write Description BrowserViewURL Read only Provides a URL that can be used to present an HTML view of the original item.Filtering APIs IArchivingControl interface for Exchange filtering Table 6-2 IArchivingControl properties (continued) Property Read/Write Description ReArchiveStatus Read only Indicates if current archiving action is rearchiving an item that has been restored from the archive. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties. and may not be supported in a future release. AddIndexPropertyToSet Adds custom index properties to a named custom index property set. Table 6-6 IArchivingControl3 properties Method Description SenderRecipientXML Retrieves an XML document containing the sender and recipient information for the current message. MessageDirection Indicates the direction in whish the message was travelling (in relation to the domain defined as internal). EnvelopeSenderRecipientXML Retrieves an XML document containing the sender and recipient information taken from the envelope message. This method is deprecated. PutFilterProperty Sets a variable that can be queried by other filters. GetFilterProperty Retrieves value of variable set using PutFilterProperty by another filter. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties.364 Filtering APIs IArchivingControl interface for Exchange filtering Table 6-4 IArchivingControl methods (continued) Method Description AddIndexPropertySet Adds a named custom index property set. and may not be supported in a future release. integer or date. Table 6-5 IArchivingControl2 method Method Description MAPISaveChanges Enables changes to the current message to be saved. . The custom index property value can be specified as a string. Table 6-7 IArchivingControl4 method Method Description AddIndexedPropertyEx Adds custom index properties to a named custom index property set. Filtering APIs IArchivingControl :: currentVaultId Version information ■ IArchivingControl2 properties and method are available in Enterprise Vault 7.0 and later. MessageClass and MAPISaveChanges are also available in Enterprise Vault 6.0 SP5. ■ IArchivingControl3 properties are available in Enterprise Vault 6.0 SP5, Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. ■ IArchivingControl4::AddIndexedPropertyEx method is available in Enterprise Vault 10.0.1 and later. 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 IArchivingControl :: currentRetentionCategoryId The Enterprise Vault retention category to be assigned to the current item. This property is read/write. 365 366 Filtering APIs IArchivingControl :: defaultRetentionCategoryId 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 “About Retention API” on page 562. 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. Filtering APIs IArchivingControl :: deleteOriginalItem Remarks The defaultRetentionCategoryId property enables the external filter to get the default retention category for the Enterprise Vault Site. 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. 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. 367 368 Filtering APIs IArchivingControl :: Action [out, retval] BOOL *pVal Pointer to current value. Remarks When the task is running in report mode the action is ignored. 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 See “EV_ACTION enumeration” on page 356. The default action is to archive the item (ARCHIVE_ITEM enumeration value). IArchivingControl :: MAPISession This property returns a MAPI session for the current message. This property is read only. Syntax HRESULT MAPISession([out, retval] IUnknown **pUnkVal); Filtering APIs IArchivingControl :: MAPIMessage Parameters [out, retval] IUnknown **pUnkVal Pointer to MAPI session. 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 ■ See “IArchivingControl2 :: MAPISaveChanges” on page 381. IArchivingControl :: AddIndexedProperty This method enables you to add a property to the custom index metadata for the item. Note: This method is deprecated, and may not be supported in a future release. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties. See “ IArchivingControl4 :: AddIndexedPropertyEx” on page 385. 369 370 Filtering APIs IArchivingControl :: IndexedPropertiesSet Syntax HRESULT AddIndexedProperty([in] BSTR propname, [in] BSTR value); Parameters [in] BSTR propname Property name. [in] BSTR value Property value. Remarks Using this method adds the property to the default property set. Properties added using this method are always searchable and retrievable. To avoid property name clashes, you are recommended to add the property to a named property set. This will also enable you to control whether the property is searchable and retrievable. IArchivingControl :: IndexedPropertiesSet This property lists the custom index properties that have been added to the item. 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 The properties are returned as XML which can be loaded into an ISimpleIndexMetadata object using the FromXML method. See “ISimpleIndexMetadata :: FromXML” on page 267. Filtering APIs IArchivingControl :: AddIndexPropertyToSet IArchivingControl :: AddIndexPropertyToSet This method adds a custom index metadata property to a named property set. Note: This method is deprecated, and may not be supported in a future release. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties. See “ IArchivingControl4 :: AddIndexedPropertyEx” on page 385. Syntax HRESULT AddIndexPropertyToSet([in] BSTR setname, [in] BSTR propname, [in] BSTR propvalue); Parameters [in] BSTR setname Name of property set. [in] BSTR propname Name of property. [in] BSTR propvalue Value of property. Remarks The searchable and retrievable settings for the property set will define how the property is handled. If the property set exists, the property will be added to that property set. If it does not exist, the property set will be created first. If a property set is created "by default", it will have the default attributes of searchable ="true" and retrievable ="false". If a property needs to be retrievable, the property set needs to be created, where the values for searchable and retrievable can be set explicitly. Properties can be multi-valued. When adding a property, the existence of that property within the specified set is checked and, if present, the value is added as an element of that property. 371 372 Filtering APIs IArchivingControl :: AddIndexPropertySet IArchivingControl :: AddIndexPropertySet This method adds a named custom property set. Note: This method is deprecated, and may not be supported in a future release. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties. See “ IArchivingControl4 :: AddIndexedPropertyEx” on page 385. Syntax HRESULT AddIndexPropertySet([in] BSTR setname, [in] BOOL searchable, [in] BOOL retrievable); Parameters [in] BSTR setname The name of the property set. Suitable names would be your company name or the filter application name. [in] BOOL searchable Setting the value to "true" means that properties in the set will be indexed. [in] BOOL retrievable Setting the value to "true" means that property values can be returned as part of the search results. The default is "false". Remarks Properties added can be grouped in named property sets. It is good practice to use a named property sets in order to avoid name clashes with other filter additions. The property set names, Vault, EnterpriseVault, KVS, Veritas, and Symantec are reserved. Properties defined as Searchable can be searched for using the Search API. Properties defined as Retrievable can be retrieved and displayed later with the item. Each property set can be marked as Searchable or Retrievable or both. See “SimpleIndexMetadata object” on page 256. Property sets do not need to be created before properties are added to them. Filtering APIs 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 ■ See “IArchivingControl :: RetryStatus” on page 377. ■ See “IArchivingControl :: ReArchiveStatus” on page 378. 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: 373 374 Filtering APIs IArchivingControl :: AgentAssignedRetentionCategoryId ■ Mailbox ■ Journaling ■ PublicFolder IArchivingControl :: AgentAssignedRetentionCategoryId This property identifies the original retention category assigned, in case other filters have assigned a different retention category. 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 “About Retention API” on page 562. 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 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. IArchivingControl :: PutFilterProperty This method is used to set a filter property that is passed on to subsequent filters. Syntax HRESULT PutFilterProperty ([in] BSTR Key, [in] BSTR Setting); 375 376 Filtering APIs IArchivingControl :: AttachmentAction 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. 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 Caution: This property is not currently supported. Filtering APIs IArchivingControl :: RetryStatus With Exchange server filtering, if the message attributes satisfy a rule, any attachments are then evaluated using attachment attributes. When an attachment matches a rule, the action specified by ATTACHMENT_ACTION is applied to the attachment. See “EV_ATTACHMENT_ACTION enumeration” on page 356. 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. See “EV_RETRY_STATUS enumeration” on page 357. See also ■ See “IArchivingControl :: TransactionID” on page 373. ■ See “IArchivingControl :: ReArchiveStatus” on page 378. 377 378 Filtering APIs IArchivingControl :: ReArchiveStatus IArchivingControl :: ReArchiveStatus If an item has been restored and is being rearchived. Remarks If this is a rearchive. the transactionID will typically be the same as the previous archive transaction. See “EV_REARCHIVE_STATUS enumeration” on page 357.retval] BSTR* pVal) . Syntax HRESULT ReArchiveStatus([out. The property is read only. The property is read only. this property enables the caller to determine if the current item is being rearchived. Parameters [out. in a database) multiple times. ■ Storing the same transaction (for example. retval] EV_REARCHIVE_STATUS* pReArchiveStatus). retval] EV_REARCHIVE_STATUS* pReArchiveStatus Pointer to an EV_REARCHIVE _STATUS type containing the current value. IArchivingControl2 :: BrowserViewURL This property returns a string containing the URL that should be entered into a web browser (for example) to view the item. This property can be used to avoid the following when processing rearchive transactions: ■ Counting the same transaction multiple times. Syntax HRESULT BrowserViewURL([out. Filtering APIs IArchivingControl2 :: NativeItemURL 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 architecture. 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 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); 379 380 Filtering APIs IArchivingControl2 :: MessageClass 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 architecture. 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 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); Filtering APIs IArchivingControl2 :: MAPISaveChanges Parameters [out, retval] BSTR *pValPointer to a string containing the MAPI message class. Remarks The value of the MAPI property, OriginalMessageClass, is returned if it exists. Otherwise the value of PR_MESSAGE_CLASS is returned. If the current item is an envelope journal message (P1), then the Message Class is returned from the P2 message. Example An example of a MAPI Message Class is: IPM.Note 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. 381 382 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> Filtering APIs IArchivingControl3 :: EnvelopeSenderRecipientXML <DN>User1</DN> <EA>SMTP Email Address</EA> </RC> </DL> </TO> <CC/> <BCC/> </RECP> <AUTH> <FROM> <DN>Display Name</DN> <EA>SMTP Email Address</EA> </FROM> </AUTH> </MSG> </ARCHIVED_ITEM> 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. 383 384 Filtering APIs IArchivingControl3 :: EnvelopeSenderRecipientXML 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> </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> Filtering APIs IArchivingControl3 :: MessageDirection 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. 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. See “Message direction enumeration” on page 358. This property is read only. IArchivingControl4 :: AddIndexedPropertyEx This method lets you add a custom index property to an item before it is archived. The method also lets you create the named property set to which the custom index property is added. You can specify the custom index property value as a string, integer, or date. Specifying the property value as a date allows you to search on the custom index property using date-based selection criteria, such as the date that the item was archived (created) or modified by Enterprise Vault. Syntax HRESULT AddIndexedPropertyEx([in] BSTR setname, [in] BSTR propname, [in] VARIANT propvalue, [in] VARIANT_BOOL searchable, [in] VARIANT_BOOL retrievable) 385 386 Filtering APIs IArchivingControl4 :: AddIndexedPropertyEx Parameters [in] BSTR setname Name of the property set to which the property is added. If the specified property set does not exist, it is created. [in] BSTR propname Name of the property. [in] VARIANT propvalue Value of the property. Table 6-8 lists the supported variant types. [in] VARIANT_BOOL searchable Defines whether the property is added to the item index. If the value is set to "VARIANT_TRUE", the property is indexed. [in] VARIANT_BOOL retrievable Defines whether the property values can be requested in search results. If the value is set to "VARIANT_TRUE", the property value can be returned as part of the search results. Remarks Call the method repeatedly to add multiple properties, or add multiple values to the same property. Table 6-8 lists the supported variant types for propvalue. Table 6-8 Supported types for propvalue Value type Variant type Note String VT_BSTR Datetime VT_DATE Limited to the UTC date range 1st January 1970 to 1st January 2038 Integer VT_UI1, VT_UI2, VT_UI4, VT_UI8, VT_I1, VT_I2, VT_I4, VT_I8, VT_INT, VT_UINT, or VT_DECIMAL Limited to the range 0 to 4,294,967,294 Hints and tips on adding custom index properties are provided in the introduction to the Content Management API.. See “Adding custom index metadata” on page 72. Filtering APIs IArchivingControl4 :: AddIndexedPropertyEx If you use Dtrace to trace the Enterprise Vault archiving task that is enabled for external filtering, you can specify the following options to trace custom index properties added using AddIndexedPropertyEx: DT>f Manage trace entry filter....(? for help) DT Filter>v Current Filter Settings: Include strings: ExternalFiltering EVFilterController IndexedPropertiesSet Details of the custom index properties that are added using AddIndexedPropertyEx are described using XML. The following is an example of the XML encoded custom index property data generated using AddIndexedPropertyEx: <?xml version="1.0" encoding="UTF-16"?> <ARCHIVED_ITEM version="1.0"> <MSG> <PROPSETLIST> <PROPSET NAME="PS_EX"> <PROP NAME="PV_STR" SEARCH="y" RESULTS="n"> <VALUE>Legal</VALUE> </PROP> <PROP NAME="PV_DATE" SEARCH="y"> <VALUE type="VT_DATE">2011-09-27T09:51:55Z</VALUE> </PROP> <PROP NAME="PV_INT" SEARCH="y" RESULTS="n"> <VALUE type="VT_I4">10</VALUE> <VALUE type="VT_UI4">100</VALUE> </PROP> </PROPSET> </PROPSETLIST> </MSG> </ARCHIVED_ITEM> VALUE type attributes are only set for dateTime and integer value types. These attributes are not set for the default value type, string. 387 388 Filtering APIs IArchivingControl4 :: AddIndexedPropertyEx SEARCH and RESULT attributes are set at PROP element level, not PROPSET level. They are only present if the value is not the default value. The default values for SEARCH and RESULT attributes are SEARCH = "n", RESULTS = "y". dateTime values are specified in UTC "yyyy-mm-ddThh:mm:ssZ" format. No time zone offset value is specified. Return value E_INVALIDARG An unsupported property type has been specified, or the value specified is not within the supported property value range. C++ examples Adding a new searchable, non-retrievable, string value type custom index property: HRESULT hr (S_OK); CComPtr<IArchivingControl4> spArchControl; _variant_t varStr (L"Legal"); hr = spIArchControl->AddIndexedPropertyEx(_bstr_t(L"PS_EX"), _bstr_t(L"PV_STR"),varStr, VARIANT_TRUE, VARIANT_FALSE); Adding a new searchable, retrievable, date value type custom index property: DATE dateNow = 0; SYSTEMTIME stNow = {0}; ::GetSystemTime(&stNow); ::SystemTimeToVariantTime(&stNow, &dateNow); _variant_t varDate = _variant_t(dateNow,VT_DATE); hr = spIArchControl->AddIndexedPropertyEx(_bstr_t(L"PS_EX"), _bstr_t(L"PV_DATE"), varDate, VARIANT_TRUE, VARIANT_TRUE); Adding a new searchable, non-retrievable, multi-valued, integer type custom index property: long lValue = 10; hr = spIArchControl->AddIndexedPropertyEx((_bstr_t(L"PS_EX"), _bstr_t(L"PV_INT"), _variant_t(lValue), VARIANT_TRUE, Filtering APIs Domino Filtering and File System Filtering APIs VARIANT_FALSE); ULONG ulValue = 100; hr = spIArchControl->AddIndexedPropertyEx((_bstr_t(L"PS_EX"), _bstr_t(L"PV_INT"), _variant_t(ulValue), VARIANT_TRUE, VARIANT_FALSE); Domino Filtering and File System Filtering APIs The Domino Filtering and File System Filtering APIs are both presented as a set of .NET interfaces. The APIs have the following interfaces in common: ■ IExternalFilter ■ IArchivingControl The IFileArchivingControl and ILotusArchivingControl interfaces are derived from IArchivingControl, and refine the interface for the different archiving target stores. ■ IIndexMetadata ■ IIndexProperty ■ IKeyedList About the Domino Filtering API The Domino Filtering API enables you to create external filters for Domino Journaling tasks. The filters define how the Domino Journaling task selects and processes messages. ■ Messages can be selected by matching one or more attributes, such as email addresses, subject text or message direction. ■ Additional properties can be added to the Enterprise Vault index for the message. ■ The action defined for the task can be to archive the message, mark it as "do not archive", or delete it. Marking messages reduces the overhead on the archiving task, as these messages are not re-evaluated during subsequent archiving runs, unless the Override registry setting is configured. See Domino filtering registry settings 389 390 Filtering APIs Domino Filtering and File System Filtering APIs Figure 6-2 Overview of Domino filtering Enterprise Vault Server Enterprise Vault Domino Journaling task Vault store Modified contents External filter 1 ProcessFilter() Task Filter Controller Modified contents The figure, Figure 6-2, illustrates how Enterprise Vault implements Domino journal filters: ■ If the registry settings are configured to enable filtering for the Domino Journaling tasks, the Domino Journaling task calls the task filter controller when processing a message in the Domino journal database. ■ The 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. Filtering APIs Domino Filtering and File System Filtering APIs About the File System Filtering API The File System Filtering API enables you to create external custom filters for File System Archiving tasks. A filter defines how the File System Archiving task selects and processes files. Files can be selected by matching one or more attributes, such as file name or file type. Additional properties can be added to the Enterprise Vault index for the file. The action defined for the selected files can be one of the following: ■ Apply the policy that is associated with the volume or folder in which the file is located. ■ Archive the file with or without creating a shortcut. ■ Archive the file and delete the original, without creating a shortcut. ■ Delete the file without archiving it. ■ Do not archive the file. A filter can also request the archiving task to shut down. Filtering can be used for a variety of reasons, such as being able to select which files to archive, providing additional statistics on files, and adding proprietary information to files that are archived by Enterprise Vault. Filters can pass the selected file to a third-party application for additional processing. For example, files can be passed to file classification or file decryption applications. The filter can pass additional information to Enterprise Vault for indexing, or alter the way the file is processed based on its classification. Classification information added to files is then available to Enterprise Vault search applications, such as Discovery Accelerator. If a file that has already been archived is processed by a filter, the following actions are not applied: ■ Modifying file properties, index properties or retention category. ■ File stream operations. Only the following subset of filter actions can be applied when processing such files: ■ Create a shortcut. ■ Delete the original file on the file server. ■ Stop the archiving task. The File System Filtering API requires Enterprise Vault 10.0 or later. 391 Methods and properties provide the filter with access to the file contents or datastream. . ■ The filter then processes the file. ■ The filter uses the methods and properties on the IFileArchivingControl interface to retrieve information about the file. illustrates how Enterprise Vault implements file system filters: ■ If the registry settings are configured to enable filtering for the File System Archiving task. provided the stopFiltering parameter is not set to TRUE. ■ The task filter controller invokes the first external filter. the task filter controller ensures that the modifications are saved back to the file on the file server using CIFS. each external filter is applied in turn to the message.392 Filtering APIs Domino Filtering and File System Filtering APIs Figure 6-3 Overview of file system filtering Enterprise Vault Server File C I F S Enterprise Vault File System Archiving task File Vault store Modified contents cache External filter 1 ProcessFilter() Task Filter Controller Modified contents The figure. which implements the IExternalFilter interface. the FilteringComplete method for each filter is called to perform any clean up tasks. If the filter makes any modifications to the file. Methods and properties on the IFileArchivingControl interface enable you to define how the archiving task is to process the file. ■ After all the filters have been applied. ■ If there are several filters. Figure 6-3. the archiving task calls the task filter controller when processing a file in the file system archiving target. ■ The File System Archiving task then processes the file according to the properties set by the external filters. Failure to load a filter is also reported in this section. The information shows the number of files or alternate data streams on which the archiving task has performed each filter action. action can be one of the following: ■ Applied filtering action The archiving task has performed the action defined by the FSAAction enumeration value.. If files that have already been archived are processed by a filter.action.FilterInterfaces.NET assembly: ■ Symantec. ■ Modified index properties Index properties have been added or removed. This information is shown in the form: [ filter_name . Filters developed using the Domino Filtering and File System Filtering APIs must reference the .. ■ Performed file stream operation A file or alternate data stream has been opened to read or write. . Developing external filters Note: If you plan to supply data to your external filters using XML. action.. In the detailed information for each file processed.. the Filter Modifications column shows the filter actions that have been performed on the file.EnterpriseVault. ] [ filter_name . External Filter Summary. KB 815112. The report files are located in the Reports\FSA subfolder of the Enterprise Vault installation folder. action.action. and action identifies the type of filter action that the archiving task has performed.NET applications.dll The API interfaces are loaded within the namespace: 393 . ■ Applied retention category The retention category has been changed.. This is described in the knowledge base article. be aware that Microsoft does not support the use of MSXML (Microsoft's COM-based XML parser) in . ■ Modified file properties File attributes have been modified. Therefore only Applied filtering action is reported for these files. . information is added to the File System Archiving task report file. ] . only the filtering action can be applied.. where filter_name is the name of the external filter. Summary information for each external filter is displayed in the report section.Filtering APIs Domino Filtering and File System Filtering APIs About file system filter reports When external filters are configured for File System Archiving. then you can create them.EnterpriseVault. The value of the filter name is a string value that contains the name of the .dll! Symantec.EnterpriseVault. if you want to use the Lotus C API for Lotus Notes/Domino to access the note. For clarity.NET assembly and the fully qualified filter class name for the new external filter: PathToFilterAssembly!FilterClassName A fully-qualified class name includes the namespace. Filter names must be an unbroken numbered sequence starting at 1.Domino.FilterInterfaces You can develop external filters in the programming language of your choice. To develop an external filter for Domino journaling. An example file system filter in managed C# is provided in the SDK. we recommend that you use managed C++.EnterpriseVault. if the class name is CustomFilter. For example. For Domino filters. definitions are given using C#.NET syntax. To develop an external filter for File System Archiving.DominoCustomFilter.394 Filtering APIs Domino Filtering and File System Filtering APIs ■ Symantec.dll assembly. you need to obtain and install an Enterprise Vault File System Archiving license. and the filter is implemented in Symantec. then the value of the registry setting should be as follows: Symantec. the namespace is Symantec.DominoCustomFilter.CustomFilter .Domino. Domino filtering registry settings Filtering for Enterprise Vault Domino Journaling tasks is enabled on the Enterprise Vault server using registry settings under the External Filtering key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Lotus Journaling If either External Filtering or Lotus Journaling keys do not exist.EnterpriseVault. The Lotus C API for Lotus Notes/Domino is shipped with the Lotus Notes client. you need to obtain and install an Enterprise Vault Lotus Domino Journaling license.EnterpriseVault. 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.EnterpriseVault.Filtering APIs Domino Filtering and File System Filtering APIs Note that the class name is case sensitive.LotusDomino. you can create a DWORD entry with the name Override.LotusDominoMsgHandler. the namespace is Symantec. if the class name is CustomFilter. and the filter is implemented in 395 . then you can create them. File System filtering registry settings Filtering for Enterprise Vault File System Archiving tasks is enabled on the Enterprise Vault server using registry settings under the External Filtering key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \File System If either External Filtering or File Systemkeys do not exist.FileSystem. To implement changes to the registry settings. you must rename the Journaling Connector to ensure that it remains last in the sequence. For example. restart the associated Domino Journaling tasks. KVS.dll! KVS. if it does not exist. If the value is 0.EnterpriseVault. Set its value to 0 (zero). then the Domino Journaling task does not reexamine the messages. If you have installed the Compliance Accelerator Journaling Connector.EnterpriseVault. The value of the filter name is a string value that contains the name of the . You create a new string entry for each filter under the File System key. When you add other filters. or the Override entry does not exist. Optionally. 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.NET assembly and the fully-qualified filter class name for the new external filter: PathToFilterAssembly!FilterClassName A fully-qualified class name includes the namespace.CADominoFilter then it must be the last in the sequence of filters. the default value is 100. The settings are added as key/value pairs. If the associated File System Archiving task is currently processing archiving targets.0" encoding="utf-8"?> <configuration> <configSections> <section name="FSAFilter" type="System. The following example shows the file with the settings added: <?xml version="1. then the default value is "0". During archiving. If the setting value is "1".config. The MaxFilterError setting lets you configure the maximum number of errors permitted before the archiving task stops.dll assembly. This section must also be declared in the <configSections> element. the archiving task keeps a count of the number of filtering errors reported.FileSystemCustomFilter. or continues to archive. If the setting value is "0". You can use the XML configuration file. then the value of the registry setting should be as follows: Symantec.dll! Symantec.DictionarySectionHandler"/> </configSections> <FSAFilter> . The configuration file is located in the Enterprise Vault installation folder.CustomFilter Note that the class name is case sensitive.EnterpriseVault. EVFSAArchivingTask.exe. you need to restart the task to implement changes to the registry settings. then the archiving task loads the next filter. This setting controls the action taken by the archiving task if it cannot load a filter. You can add the following settings for file system filtering: ■ MoveOnFilterFailure. the archiving task stops if it cannot load the filter.EnterpriseVault. then the archiving task stops. You need to edit the file and add a section called <FSAFilter> to hold the settings.FileSystem.Configuration. to control the behavior of the archiving task in the event of filter errors. If the setting is not present in the configuration file. ■ MaxFilterError.EnterpriseVault.FileSystemCustomFilter.396 Filtering APIs Domino Filtering and File System Filtering APIs Symantec. If the setting is not present in the configuration file. 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. or continue to archive.Filtering APIs Enumerations (Domino filtering) <add key="MaxFilterError" value = "150"/> <add key="MoveOnfilterFailure" value = "1"/> </FSAFilter> <runtime> <generatePublisherEvidence enabled="false"/> </runtime> </configuration> The settings in this example file have the following effect: ■ key="MaxFilterError" value = "150" — The archiving task will stop if more than 150 filtering errors are reported. ■ key="MoveOnfilterFailure" value = "1" — If the archiving task cannot load a filter. ARCHIVE_ITEM = 1. Enumerations (Domino filtering) This section lists the enumerations for the Domino Filtering API. it will try to load the next filter. DIRECTION_INTERNAL = 1. 397 . Message direction enumeration The following enumeration values are defined for MSG_DIRECTION: public enum MSG_DIRECTION { DIRECTION_UNDEFINED = 0. 3. 1. Note that this option requires Enterprise Vault 8. Enumerations (File System Filtering) This section lists the enumerations for the File System Filtering API. . MARK_DO_NOT_ARCHIVE Mark the item as processed but do not archive it.0 SP5 or later. See “Domino filtering registry settings” on page 394. HARD_DELETE = 4. REQUEST_SHUTDOWN Shut down the archiving task. 5. These actions can be set by the external filter. HARD_DELETE Hard delete the item without archiving it. 2. File System Archiving action enumeration The following actions are supported by the filter controller. The Domino Journaling task does not reexamine marked messages unless the Override setting is configured.398 Filtering APIs Enumerations (File System Filtering) MARK_DO_NOT_ARCHIVE = 2. REQUEST_SHUTDOWN = 5 } Table 6-9 DominoAction enumeration values Value Action NO_ACTION Do not archive. ARCHIVE_ITEM (Default) Archive the item according to the assigned policy. delete or mark the item. public enum FSAAction { DEFAULT_POLICYACTION ARCHIVE_CREATESHORTCUT ARCHIVE_DONOTCREATESHORTCUT DONOTARCHIVE DELETE REQUEST_SHUTDOWN = = = = = = 0. 4. The file is left in its original location. IExternalFilter interface The external filter must implement the IExternalFilter interface.FilterInterfaces.dll Syntax public interface IExternalFilter 399 . (Vault store backup properties are honored). No shortcut is created. which is called by the archiving task filter controller: Namespace: Symantec. REQUEST_SHUTDOWN Shut down the archiving task. DONOTARCHIVE Do not archive the file.Filtering APIs IExternalFilter interface ARCHIVE_DELETE = 6 } Table 6-10 FSAAction enumeration values Value Action DEFAULT_POLICYACTION (Default) Perform the action specified in the policy that is applied to the volume or folder in which the file is located.EnterpriseVault.EnterpriseVault. ARCHIVE_CREATESHORTCUT Archive the file and create a shortcut. ARCHIVE_DELETE Archive the file and delete the original. ARCHIVE_DONOTCREATESHORTCUT Archive the file and do not create a shortcut. DELETE Delete the file without archiving it.FilterInterfaces Assembly: Symantec. 400 Filtering APIs IExternalFilter :: Initialize Member summary Table 6-11 Member summary Method Description Initialize Called during the archiving task initialization. The ProcessFilter method is where you process the item to your requirements. The filter should perform any necessary initialization before item processing begins. FilteringComplete Called after all filters have been processed for the current item. Requirements IExternalFilter :: Initialize This method is called during archiving task initialization. Remarks Filters are instantiated at task startup and released at task shutdown. The ProcessFilter method is where you process the item to your requirements. Syntax void Initialize(). The filter should perform any necessary initialization before item processing begins. Syntax void ProcessFilter(IArchivingControl archivingControl. ProcessFilter Called per-item during the archiving process. Shutdown Called during the archiving task shutdown. . ref bool stopFiltering). The filter should perform any necessary clean-up tasks. IExternalFilter :: ProcessFilter This method is called per-item during the archiving process. ■ See “IFileArchivingControl interface” on page 410. Syntax void Shutdown(). IExternalFilter :: FilteringComplete This method is called after all filters have been processed. As the archiving task runs in multiple threads. ref bool stopFiltering True value prevents any further filters from being processed for the current item. ■ See “ILotusArchivingControl interface” on page 406.Filtering APIs IExternalFilter :: FilteringComplete Parameters IArchivingControl archivingControl Reference to the ILotusArchivingControl or IFileArchivingControl interface. IExternalFilter :: Shutdown This method is called during archiving task shutdown. Remarks The archivingControl reference is used by the filter in the callback to obtain information about the current item and take appropriate actions. the external filter must be written to handle concurrent calls. See also ■ See “IArchivingControl interface” on page 402. Remarks This method can be used to clean up resources used to filter the item. it must use appropriate concurrency protection. If the filter accesses a shared resource. 401 . Syntax void FilteringComplete(). The IFileArchivingControl interface is implemented by the File System archiving task filter controller.FilterInterfaces.EnterpriseVault. See “ILotusArchivingControl interface” on page 406. The ILotusArchivingControl interface is implemented by the Domino archiving task filter controller. Syntax public interface ILotusArchivingControl : IArchivingControl public interface IFileArchivingControl : IArchivingControl Member summary Table 6-12 IArchivingControl properties Property Read/Write Description OriginalVaultID Read only Original archive for the current item.dll The methods properties of the interfaces enable an external filter to retrieve and modify properties on the current item. See “IFileArchivingControl interface” on page 410. CurrentVaultID Read/Write Target archive for the current item. It extends the IArchivingControl interface to provide access to Domino messages from Domino filters.EnterpriseVault. .402 Filtering APIs IArchivingControl interface Remarks The filter should perform any necessary clean-up tasks. and is passed to the filter on a per-message basis during the ProcessFilter call. It extends the IArchivingControl interface to provide access to file system archiving targets from file system archiving filters.FilterInterfaces Assembly: Symantec. and is passed to the filter on a per-item basis during the ProcessFilter call. IArchivingControl interface This task filter controller implements the following interfaces: ■ IArchivingControl ■ ILotusArchivingControl ■ IFileArchivingControl Namespace: Symantec. In file system filtering. If a filter changes the target archive for the item. the value returned is the archive folder Id for the file. or to be added. to the current item. Syntax string OriginalVaultID {get. Attempts to set a value will throw the exception. NotSupportedException. IArchivingControl :: OriginalVaultID Retrieves the original archive ID for the current item. Syntax string CurrentVaultID {get. In file system filtering. this property will remain unchanged. In file system filtering. this property is read only.Filtering APIs IArchivingControl :: OriginalVaultID Table 6-12 Property IArchivingControl properties (continued) Read/Write Description OriginalRetentionCategoryID Read only Original retention category for the current item. IndexData Read only Metadata added. This property is read-only.} Remarks This property holds the archive ID originally assigned by the archiving task before any filters where processed. this property is read/write. set. FilterProperties Read only A collection of properties for the current item. IArchivingControl :: CurrentVaultID This property retrieves or sets the ID of the archive in which the current item will be stored. CurrentRetentionCategoryID Read/Write Retention category assigned to current item. the value returned is the archive folder Id for the file. In Domino filtering.} 403 . Example An example value for this property is: 190901BF3D1D1364084C418053F8122C31110000EVArchiveSite1 IArchivingControl :: OriginalRetentionCategoryID This property holds the original retention category ID for the current item. this property will remain unchanged.404 Filtering APIs IArchivingControl :: OriginalRetentionCategoryID Exception NotSupportedException Setting this property is not supported by File System Filtering. IArchivingControl :: CurrentRetentionCategoryID This property defines the retention category for the current item. Syntax string CurrentRetentionCategoryID {get.} Remarks Use this property to set or retrieve the ID of the retention category assigned to the current item. before any filters where processed. An example value is: 18306BF113C2C444096279660836252821b10000EVArchiveSite1 .} Remarks This property holds the Id of the retention category originally assigned by the archiving task. This property is read-only. This property is read/write. If a filter changes the retention category for the item. Syntax string OriginalRetentionCategoryID {get. set. For example. a filter property can be set by one filter and queried by another. IArchivingControl :: FilterProperties This property is an instance of the IKeyedList interface. or does not exist.} Remarks The properties listed are shared across all filters. The property is read only.} Remarks See also ■ See “IIndexMetadata interface” on page 424. The properties can be maintained across multiple messages. Syntax IIndexMetadata IndexData {get. 405 . and enables access to the custom index metadata for the current item. ArgumentException Value specified is empty. Syntax IKeyedList FilterProperties {get. The property is read only. IArchivingControl :: IndexData This property is an instance of the IIndexMetadata interface. and enables communication between multiple filters. if required.Filtering APIs IArchivingControl :: IndexData Exceptions ArgumentNullException Value specified is null. These properties are not stored in Enterprise Vault or reset by Enterprise Vault. DatabaseName Read only Path to current journal database.FilterInterfaces. set. SenderRecipientXML Read only XML representation of message distribution list. Namespace: Symantec.dll See “IArchivingControl interface” on page 402.} . and extends the interface to enable filters to access Domino messages. StoreIdentifier Read only Unique Id of Domino message.406 Filtering APIs ILotusArchivingControl interface See also ■ See “IKeyedList interface” on page 431.FilterInterfaces Assembly: Symantec.EnterpriseVault. Direction Read only Direction of message (internal or external). DatabaseHandle Read only Handle to current journal database. ILotusArchivingControl interface ILotusArchivingControl is derived from the IArchivingControl interface. NoteHandle Read only Handle to current message.EnterpriseVault. ILotusArchivingControl :: Action This property defines the filtering action for the current message. Syntax DominoAction Action {get. The property is read/write. Member summary Table 6-13 ILotusArchivingControl properties Property Read/Write Description Action Read/Write Defines filtering action for current message. The default action is to archive the item (ARCHIVE_ITEM enumeration value). The property is read only. The property is read only.Filtering APIs ILotusArchivingControl :: NoteHandle Remarks The filtering action is defined by the DominoAction enumeration.} Remarks This handle must not be closed by the filter. Syntax IntPtr NoteHandle {get. ILotusArchivingControl :: NoteHandle This property retrieves the Lotus C API for Lotus Notes/Domino handle to the current message. See “Domino action enumeration” on page 397. 407 . ILotusArchivingControl :: DatabaseHandle This property retrieves the Lotus C API for Lotus Notes/Domino handle to the current database. ILotusArchivingControl :: DatabaseName This property retrieves the current Domino journal database path. The property is read only. Syntax IntPtr DatabaseHandle {get.} Remarks This handle must not be closed by the filter. } Remarks This path is relative to the Data folder. including expanded distribution lists. This document is described by the following DTD: <!ELEMENT MSG (RECP. DL*)> <!ELEMENT BCC (RC*. PP)> <!ELEMENT FROM (DN.} Remarks Any distribution lists are expanded. EA+)> <!ELEMENT DN (#PCDATA)> <!ELEMENT EA (#PCDATA)> <!ELEMENT DL (DN. The property is read only. CC. RC*)> <!ELEMENT AUTH (FROM. 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. AUTH)> <!ELEMENT RECP (TO.408 Filtering APIs ILotusArchivingControl :: SenderRecipientXML Syntax string DatabaseName {get. ILotusArchivingControl :: SenderRecipientXML This property retrieves an XML document containing the sender and recipient information for the current message. DL*)> <!ELEMENT RC (DN. The property value is an XML document representing the sender and recipient information for the current message. EA)> <!ELEMENT PP (DN?. EA?)> <!ATTLIST EA TYPE CDATA #REQUIRED> . Syntax XmlDocument SenderRecipientXML {get. BCC)> <!ELEMENT TO RC*. EA. DL*)> <!ELEMENT CC (RC*. Filtering APIs ILotusArchivingControl :: StoreIdentifier Example The following is an example of the SenderRecipientXML document: <!--The <RECP> element lists all the message recipients in TO. BCC fields. If distribution lists are present. If the message was sent by a delegate. 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> <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. CC. 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> ILotusArchivingControl :: StoreIdentifier This property uniquely identifies the message. SMTP and Lotus Notes format addresses for the message author. 409 . Every copy of a note has the same UNID.FilterInterfaces Assembly: Symantec.410 Filtering APIs ILotusArchivingControl :: Direction The property is read only.} Remarks The property value is an enumerated value. Syntax string StoreIdentifier {get. Syntax MSG_DIRECTION Direction {get.} Remarks The property is derived from the Universal Note ID (UNID) and Originator ID (OID) that are assigned by the Domino server. but the OID changes when the note is modified.dll See “IArchivingControl interface” on page 402. Namespace: Symantec.EnterpriseVault. . ILotusArchivingControl :: Direction This property indicates the direction in which the message was travelling (in relation to the domain defined as internal). IFileArchivingControl interface The IFileArchivingControl interface is derived from IArchivingControl. The UNID and OID are defined as follows: UNID (Universal Note ID) Identifies all the copies of a note. See “Message direction enumeration” on page 397.EnterpriseVault. Every copy of a note has the same OID. and the UNID does not change when a note is modified. regardless of location. OID (Originator ID) Identifies a particular revision of a note. and refines the interface for file system archiving targets.FilterInterfaces. regardless of location or time. writes and searches for the file contents (default stream). ExtendedAttributes Read only Retrieves the extended attributes of the file. Open Reads. OpenStream Reads. writes and searches for the alternate data streams. Attributes Read/Write Retrieves or modifies the file attributes. Name Read/Write Retrieves or modifies the file name only. LastWriteTimeUtc Read/Write Retrieves or modifies the last modified date (UTC) of the file. Length Read only Retrieves the size of the file. LastAccessTimeUtc Read/Write Retrieves or modifies the last accessed date (UTC) of the file.Filtering APIs IFileArchivingControl :: Action Member summary Table 6-14 IFileArchivingControl properties Property Read/Write Description Action Read/Write Retrieves or modifies the action for the current item. DeleteStream Deletes an alternate data stream. StreamNames Lists all alternate data streams. Table 6-15 Method Read only IFileArchivingControl methods Description GetAccessControl Retrieves the access control of the file. 411 . CreationTimeUtc Read/Write Retrieves or modifies the creation date (UTC) of the file. SetAccessControl Modifies the access control of the file. IFileArchivingControl :: Action This property defines the filtering action for the current item. The property is read/write. Exception ArgumentOutOfRangeException Value specified is an invalid value for FSAAction.412 Filtering APIs IFileArchivingControl :: Name Syntax FSAAction Action {get. Remarks The filtering action is defined by the FSAAction enumeration. The property is read/write.} Value string FileName File name of the current item. set.} Value Action FSAAction enumeration value. and can be used to rename the file. By default the action taken is the one defined in the policy for the folder or volume in which the file is located. IFileArchivingControl :: Name This property holds the file name of the current item. set. Syntax string Name {get. Remarks The value does not include the path to the file. . See “File System Archiving action enumeration” on page 398. txt". // rename file as fileName.FileAttributes Attributes System. 413 . Example string fileName = archivingControl. or the path specified is read-only. FilterControllerException For any other errors during the operation (for example.FileAttributes Attributes {get. or both exceed the system-defined maximum length. The property is read/write. or the filename specified includes invalid characters. IFileArchivingControl :: Attributes This property provides the file attributes of the current item.IO. UnathorizedAccessException The caller does not have the required permission.Filtering APIs IFileArchivingControl :: Attributes Exceptions ArgumentNullException Value specified is null. Syntax System. Inner exception will provide information about the actual error.Name = fileName + ".Name. Filenames cannot include any of the following characters: /\:?”<>| PathTooLongException The specified path. ArgumentException A file with the specified name already exists.IO. filename.IO.txt archivingControl.FileAttributes enumeration value.} Value System. an IO error). set. Filename cannot be more than 255 characters. Example IFileArchivingControl :: CreationTimeUtc This property provides the date and time (UTC) when the current item was created.} Value System. FilterControllerException For any other errors during the operation (for example. set. Inner exception will provide information about the actual error.DateTime CreationTimeUtc {get. NoteSupportedException One or more unsupported file attribute has been specified: Device. Directory.414 Filtering APIs IFileArchivingControl :: CreationTimeUtc Remarks Setting the following file attributes is not supported: ■ Directory ■ Device ■ Offline ■ Temporary Exceptions UnathorizedAccessException The caller does not have the required permission. Temporary. . or the path specified is read-only. Offline. an IO error). The property is read/write.DateTime CreationTimeUtc UTC datetime. Syntax System. set. 415 .DateTime LastAccessTimeUtc {get. or times.} Value System. or the path specified is read-only. or the path specified is read-only. Syntax System. or both. or times. Inner exception will provide information about the actual error. and the access is other than read. an IO error). that are permitted for this operation. UnathorizedAccessException The caller does not have the required permission. The property is read/write.DateTime LastAccessTimeUtc UTC datetime Exceptions ArgumentOutOfRangeException The value specified is outside the range of dates. Example IFileArchivingControl :: LastAccessTimeUtc This property provides the date and time (UTC) when the current item was last accessed. or both. UnathorizedAccessException The caller does not have the required permission. and the access is other than read. FilterControllerException For any other errors during the operation (for example. that are permitted for this operation.Filtering APIs IFileArchivingControl :: LastAccessTimeUtc Exceptions ArgumentOutOfRangeException The value specified is outside the range of dates. Syntax System. The property is read/write.} Value System.DateTime LastWriteTimeUtc {get. FilterControllerException For any other errors during the operation (for example. or the path specified is read-only.DateTime LastWriteTimeUtc UTC datetime Exceptions ArgumentOutOfRangeException The value specified is outside the range of dates. UnathorizedAccessException The caller does not have the required permission. set. or both. that are permitted for this operation. Inner exception will provide information about the actual error. an IO error). an IO error). or times. Example IFileArchivingControl :: LastWriteTimeUtc This property provides the date and time (UTC) when the current item was last modified.416 Filtering APIs IFileArchivingControl :: LastWriteTimeUtc FilterControllerException For any other errors during the operation (for example. . Inner exception will provide information about the actual error. AccessControl. Syntax System.Security.NET Framework AccessControlSections enumeration in the System.AccessControl namespace.AccessControl.AccessControl namespace.FileSecurity fileSecurity).Filtering APIs IFileArchivingControl :: GetAccessControl Example IFileArchivingControl :: GetAccessControl This method returns the access control that is set on the current file.FileSecurity GetAccessControl( AccessControlSections includeSections).Security.AccessControl.NET Framework AccessControlSections enumeration in the System. The method uses the . Parameter AccessControlSections includeSections AccessControlSections enumeration value. 417 . Exception NotImplementedException Example IFileArchivingControl :: SetAccessControl This method sets the access control on the current file. Parameter System. The method uses the . FileSecurity fileSecurity AccessControlSections enumeration value.Security.Security.Security. Syntax void SetAccessControl( System. UInt64 Length {get.UInt64 Length Size of file in bytes. FileAccess enumeration Specifies how the operating system should open a file. Syntax System.IO.NET Framework enumerations in the System. Syntax System. FileShare share). FileAccess access. or read/write access to a file. write.IO namespace: FileMode enumeration Defines constants for read. The method uses the following .418 Filtering APIs IFileArchivingControl :: Length Exceptions NotImplementedException Example IFileArchivingControl :: Length This property provides the size of the current file.} Value System. FileShare enumeration Contains constants for controlling the kind of access other FileStream objects can have to the same file.Stream Open(FileMode mode. The property is read only. . Example IFileArchivingControl :: Open This method is used to open the default stream for reading or writing. FilterControllerException For any other errors during the operation (for example. is not supported. or Append. and the FileMode specified is Truncate or Append. FileShare. or the path specified is read-only. Exceptions ArgumentOutOfRangeException The value specified for FileMode. 419 .Append The FileShare value. Remarks The following FileMode values are not supported: ■ FileMode. FileMode specified is one of Create. Inner exception will provide information about the actual error. ■ The FileAccess specified is ‘read’.Inheritable. and the access is other than read. FileShare share FileShare enumeration value.CreateNew ■ FileMode.Create ■ FileMode. an IO error). CreateNew. OpenOrCreate.Filtering APIs IFileArchivingControl :: Open Parameters FileMode mode FileMode enumeration value.OpenOrCreate ■ FileMode. or FileShare is invalid. FileAccess access FileAccess enumeration value. ArgumentException ■ UnathorizedAccessException The caller does not have the required permission. FileAccess. an IO error). Inner exception will provide information about the actual error. The method uses the following .420 Filtering APIs IFileArchivingControl :: StreamNames Example IFileArchivingControl :: StreamNames This property lists the names of alternate data streams. foreach (var v in alternateDataStreams) { // add code } IFileArchivingControl :: OpenStream This method is used to open an alternate data stream for reading or writing.StreamNames. Example string [] alternateDataStreams = archivingControl. The property is read only. or read/write access to the stream. Syntax String[] StreamNames {get. .} Value String[] StreamNames Names of alternate data stream. Exception FilterControllerException For any errors during the operation (for example.NET Framework enumerations in the System.IO namespace: FileMode enumeration Defines constants for read. write. ArgumentOutOfRangeException The value specified for FileMode.FileShare enumeration value string streamName Name of alternate data stream Remarks The FileShare value. 421 . Syntax System. Exceptions ArgumentNullException The stream name specified is null.IO. String streamName). FileShare. FileAccess or FileShare is invalid. FileShare enumeration Contains constants for controlling the kind of access other filestream objects can have to the same stream. ArgumentException The FileAccess value specified is ‘read’. is not supported.IO.FileMode enumeration value FileAccess access System.FileAccess enumeration value FileShare share System. or the path specified is read-only. and the access is other than read.Inheritable.Filtering APIs IFileArchivingControl :: OpenStream FileAccess enumeration Specifies how the operating system should open the stream.Stream OpenStream(FileMode mode. FileShare share.IO. Parameters FileMode mode System. FileAccess access. UnathorizedAccessException The caller does not have the required permission.IO. and the FileMode specified is Truncate or Append. foreach (var v in alternateDataStreams) { using(Stream ads = archivingControl. Syntax bool DeleteStream(string streamName).422 Filtering APIs IFileArchivingControl :: DeleteStream FilterControllerException For any other errors during the operation (for example. v)) { long bytesInAds = ads.Read. or the path specified is read-only.Open.Open(FileMode. FileAccess.StreamNames. Example string [] alternateDataStreams = archivingControl.Read. or has invalid characters. . Inner exception will provide information about the actual error. ArgumentException The stream name is empty. an IO error). FileShare. Parameters string streamName Name of alternate data stream Exceptions ArgumentNullException The stream name specified is null.Length. } } IFileArchivingControl :: DeleteStream This method is used to delete an alternate data stream. UnathorizedAccessException The caller does not have the required permission. String> ExtendedAttributes {get.Collections.ExtendedAttributes.Value). Exception FilterControllerException For any errors during the operation (for example. foreach (var v in extendedAttribs) Console. Syntax System. IFileArchivingControl :: ExtendedAttributes This property returns a name/value pair for the extended attributes that exist on the file. 423 .Generic.} Parameters ExtendedAttributes Name/value list.Filtering APIs IFileArchivingControl :: ExtendedAttributes FilterControllerException For any other errors during the operation (for example.Key + "EA Value:" + v.DeleteStream("adsName"). Example bool deleted = archivingControl.WriteLine("EA Name:" + v. an IO error). Inner exception will provide information about the actual error. string> extendedAttribs = archivingControl. Example Dictionary<string. an IO error).Dictionary<String. Inner exception will provide information about the actual error. Clear Remove all custom index metadata properties from the current item. When enumerating. . See “IIndexProperty interface” on page 428.FilterInterfaces. and retrieve additional properties that have been previously added to the index using Add ().FilterInterfaces Assembly: Symantec.EnterpriseVault. 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.EnterpriseVault. each property is returned as an instance of the IIndexProperty interface.424 Filtering APIs IIndexMetadata interface IIndexMetadata interface This interface enables the external filter to add properties to the custom index metadata for the current item. Add Add a custom index metadata property to the current item. See “Adding custom index metadata” on page 72. Table 6-17 IIndexMetadata methods Method Description Count Returns the current count of properties.dll Syntax public interface IIndexMetadata : IEnumerable Member summary Table 6-16 IIndexMetadata properties Property Read/Write Description DateTimeUTC Read/Write Whether date and time properties are UTC or local system time. ToXML Persists the custom index metadata to XML. Namespace: Symantec. Syntax void FromXML(string xmlIndexMetadata). as the Add method should always be used to add metadata properties. IIndexMetadata :: FromXML This method loads the custom index metadata from an XML document.Filtering APIs IIndexMetadata :: ToXML IIndexMetadata :: ToXML This method returns the custom index metadata as an XML document. Parameters bool formattedLayout If true. Remarks The XML can be loaded into an ISimpleIndexMetadata object. Parameters [in] BSTR xmlIndexMetadata The XML stream to input. the XML returned will be formatted in lines and indented appropriately. as defined in the Content Management API. See “SimpleIndexMetadata object” on page 256. 425 . Remarks Use the Add method to add item specific values. Do not change the structure of the XML. The XML schema is not published. Syntax string ToXML(bool formattedLayout). string propertyName. bool propertySearchable. DateTime propertyValue. bool propertyRetrievable). bool propertySearchable Whether property can be searched for using Search API. string propertyValue DateTime propertyValue long propertyValue ulong propertyValue Property value. bool propertySearchable.426 Filtering APIs IIndexMetadata :: Add IIndexMetadata :: Add This method adds a property to the custom index metadata for the current item. bool propertyRetrievable). Syntax void Add(string propertySet. string propertyName Name of the property. void Add(string propertySet. bool propertyRetrievable Whether property can be retrieved and displayed in search results. void Add(string propertySet. bool propertySearchable. void Add(string propertySet. string propertyName. Parameters string propertySet Name of the property set. long propertyValue. bool propertyRetrievable). string propertyValue. string propertyName. The custom index metadata will be added to the archive's item once the item has been archived. ulong propertyValue. bool propertySearchable. string propertyName. . bool propertyRetrievable). integers or dateTime values. When adding a property. VT_I8. if present.294 Properties can be multi-valued. if the property set exists.Filtering APIs IIndexMetadata :: Add Remarks The Add method can be called repeatedly to add multiple properties to the index. Table 6-18 Supported types for propertyValue Value type Variant type Note String VT_BSTR Datetime VT_DATE Limited to the UTC date range of 1st January 1970 to 1st January 2038 Integer VT_UI1. VT_UI4. the property will be added to the property set specified by propertySet. When you use Add() to add a property to the index. If the Retrievable property is true. the existence of that property within the specified property set is checked and. The default value is false. If the Searchable property is true. The property information can then be retrieved and displayed later with the item in search results. or VT_DECIMAL Limited to the range 0 to 4. VT_INT. VT_I2. 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. The overloads of the Add method allow the addition of strings. the value is added as an element of that property. VT_I4.294. It is good practice to use a named property set in order to avoid name clashes with other external filter additions. the property is stored with the item in the archive. Table 6-18 lists the supported variant types for propertyValue. VT_UI8.967. VT_I1. VT_UINT. it will be created first. Suitable names would be your company name or the filter application name. the property will be indexed. 427 . VT_UI2. If the set does not exist. IIndexProperty interface The IIndexProperty interface details a a custom index metadata property within an IIndexMetadata collection. Syntax void Clear(). set. See “Adding custom index metadata” on page 72. . Syntax int Count(). IIndexMetadata :: Count This method retrieves the number of properties in the IndexMetadata object for the current item. 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.428 Filtering APIs IIndexMetadata :: Clear Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. IIndexMetadata :: Clear This method clears all properties from the IIndexMetadata object for the current item.} Remarks This property sets or retrieves whether the date and time properties are input and output in UTC or local system time. prop.Add(prop. Name Read only The name of the property.FilterInterfaces Assembly: Symantec.Set. Searchable Read only Defines whether the property is to be added to the item index. Remarks An instance of this interface is returned when enumerating an IIndexMetadata collection.dll Syntax public interface IIndexProperty Member summary Table 6-19 IIndexProperty properties Property Read/Write Description Set Read only The name of the property set. foreach(IIndexProperty prop in custProps) { if (prop.Value).Searchable) { searchableProps.EnterpriseVault. Example [C#] IIndexMetadata custProps = archivingControl. prop. } } 429 . Retrievable Read only Defines whether the property is to be stored in the saveset. Value Read only The value assigned to the property.FilterInterfaces.IndexMetadata.Filtering APIs IIndexProperty interface Namespace: Symantec.Name.EnterpriseVault. } IIndexProperty :: Value This property holds the value of the index property. The property is read only.Object Value {get.} IIndexProperty :: Name This property holds the name of the custom index property. or date/time value. Syntax string Name {get. foreach(IIndexProperty prop in custProps) { if (prop.Value. The property is read only. Example [C#] IIndexMetadata custProps = archivingControl.430 Filtering APIs IIndexProperty :: Set IIndexProperty :: Set This property holds the name of the property set. Syntax System. The property is read only. Syntax string Set {get.IndexMetadata. integer.Searchable && (prop.} Remarks The object will be a string.GetType() == . Name. The property is read only.} IIndexProperty :: Retrievable This property indicates whether the index property can be retrieved and displayed with search results when using the Search API. Namespace: Symantec. Syntax bool Retrievable {get.Add(prop.Set. IDictionary. The property is read only. Syntax bool Searchable {get. IEnumerable 431 .FilterInterfaces Assembly: Symantec.dll Syntax public interface IKeyedList : ICollection.Filtering APIs IIndexProperty :: Searchable typeof(DateTime))) { searchableDateProps. prop.EnterpriseVault.Value). } } IIndexProperty :: Searchable This property indicates whether the property can be returned in search results when using the Search API. (DateTime)prop. The collection allows both random access by index and keyed access using a key value.} IKeyedList interface This interface enables multiple filters to access a list of filter properties.FilterInterfaces.EnterpriseVault. Int32 index.Object key The key for the filter property. Parameters System.Object value).432 Filtering APIs IKeyedList :: Insert Member summary Table 6-20 IKeyedList methods Method Description Insert Inserts a filter property into the list at the specified position. System. IKeyedList :: Insert Inserts a filter property into the list at the specified position.Int32 index The position to insert into the list.Object value The value of the filter property. Remarks The elements that follow the insertion point are moved down to accommodate the new element. . See also ■ See “IArchivingControl :: FilterProperties” on page 405. Syntax void Insert(System. RemoveAt Removes a filter property from the specified position in the list.Object key. System. System. An exception is reported if the specified index is out of range. System. then the value is appended at the end of the list. If index equals the number of items in the list. An exception is reported if the index is out of range. 433 . Parameter Int32 index The position in the list. Remarks The elements that follow the removed element move up to occupy the vacated spot.Filtering APIs IKeyedList :: RemoveAt IKeyedList :: RemoveAt Removes a filter property from the list at the specified position. Syntax void RemoveAt(Int32 index). 434 Filtering APIs IKeyedList :: RemoveAt . Chapter Search API This chapter includes the following topics: ■ About Search API ■ About storing data in Enterprise Vault ■ Introduction to Enterprise Vault indexing ■ Using the Search API ■ Constants and enumerations ■ SearchQuery object ■ ISearchQuery :: Query ■ ISearchQuery :: Clear ■ ISearchQuery :: SetTerm ■ ISearchQuery :: AddTerm ■ ISearchQuery :: SetRange ■ ISearchQuery :: AddRange ■ ISearchQuery :: SetProperty ■ ISearchQuery :: AddProperty ■ ISearchQuery :: AddOp ■ ISearchQuery :: Combine ■ ISearchQuery :: AddQuery ■ ISearchQuery2 :: SetPropertyRange 7 . 436 Search API ■ ISearchQuery2 :: AddPropertyRange ■ IndexSearch object ■ IIndexSearch2 :: IndexVolumeSets ■ IIndexSearch2 :: Options ■ IIndexSearch2 :: SortBy ■ IIndexSearch2 :: ResultsPropertySet ■ IIndexSearch2 :: AdditionalResultsProperties ■ IIndexSearch2 :: Timeout ■ IIndexSearch2 :: ArchiveEntryId ■ IIndexSearch2 :: ArchiveName ■ IIndexSearch2 :: HasFolders ■ IIndexSearch2 :: IndexVolumeSetIdentity ■ IIndexSearch2 :: IndexVolumeIdentity ■ IIndexSearch2 :: IndexVolumeSetCount ■ IIndexSearch2 :: MaxSearchIndexVolumeSets ■ IIndexSearch2 :: MaxSearchResultsPerVolumeSet ■ IIndexSearch2 :: SelectArchive ■ IIndexSearch2 :: ListIndexVolumeSets ■ IIndexSearch2 :: SelectIndexVolumeSet ■ IIndexSearch2 :: SelectIndexVolume ■ IIndexSearch2 :: Search ■ IIndexSearch2 :: SearchToXML ■ IIndexSearch2 :: AddAdditionalResultsProperty ■ IIndexSearch2 :: AddAdditionalResultsCustomProperty ■ IIndexSearch2 :: Reset ■ IndexVolumeSets object ■ IIndexVolumeSets :: ArchiveEntryId . Search API ■ IIndexVolumeSets :: ArchiveName ■ IIndexVolumeSets :: HasFolders ■ IIndexVolumeSets :: Count ■ IIndexVolumeSets :: _NewEnum ■ IIndexVolumeSets :: Item ■ IndexVolumeSet object ■ IIndexVolumeSet :: Identity ■ IIndexVolumeSet :: ArchiveEntryID ■ IIndexVolumeSet :: ArchiveName ■ IIndexVolumeSet :: FirstItemIndexSequenceNumber ■ IIndexVolumeSet :: OldestArchivedDate ■ IIndexVolumeSet :: YoungestArchivedDate ■ IIndexVolumeSet :: OldestItemDate ■ IIndexVolumeSet :: YoungestItemDate ■ IIndexVolumeSet :: DateTimesUTC ■ SearchResults object ■ ISearchResults :: Results ■ ISearchResults :: Count ■ ISearchResults :: Total ■ ISearchResults :: Start ■ ISearchResults :: Options ■ ISearchResults :: SortBy ■ ISearchResults :: _NewEnum ■ ISearchResults :: Item ■ ISearchResults2 :: InSync ■ ISearchResults2 :: TruncationReason ■ ISearchResults2 :: DateTimesUTC 437 . The Storage service compresses and stores the items (and the converted content) as savesets in the appropriate archives. a "content missing" reason is indexed using the "comr" property. The content and attachments are indexed provided there is a content converter available for the file type. and the converted content for the item as a whole (including attachments) does not exceed 100 MB. Information about each item that is archived is stored in the vault store database.438 Search API About Search API ■ ISearchResults2 :: LoadResults ■ SearchResult object ■ ISearchResult :: Result ■ ISearchResult :: Number ■ ISearchResult :: Prop ■ ISearchResult :: Prop2 ■ ISearchResult2 :: Count ■ ISearchResult2 :: Item ■ ISearchResult2 :: DateTimesUTC About Search API This chapter describes the Search API. The Storage service interoperates with the Index Servers to manage the indexes of archived data. See “ETruncationReason enumeration” on page 461. and to provide a version of the item that can be viewed in a browser. The text or HTML version is used for indexing. If the content cannot be indexed. See “System properties” on page 596. About storing data in Enterprise Vault The Enterprise Vault Storage service accepts items for archiving from the archiving tasks. Archives are grouped in vault stores. a text or HTML version of each item is generated. and also responds to requests from the archiving tasks to retrieve items. . If a suitable converter is available for the file type. which enables third-party applications to search the indexes of Enterprise Vault archives. if required. ■ In response to search requests from the Enterprise Vault Web Server. Figure 7-1 shows a standalone Index Server configuration. or in Index Server groups. Index Servers and Index Server groups The role of the Index Server can be summarized as follows: ■ On instruction from the Storage service. archive indexes. or third-party search applications using the Search API. ■ The Index Server ensures that indexes are complete. while others host Index Servers. Figure 7-2 shows an example of this environment. Index Servers can be standalone. or later. the Index Server indexes items. some Enterprise Vault servers may host Storage services. This section provides an introduction to Index Servers. This can be as the items are archived. and the indexing configuration options. An Index Server can only be standalone if the Storage service and Index Server are collocated on an Enterprise Vault server. and automatically updates the index every hour. the Index Server searches the indexes and returns information about the archived items that match the search criteria. In a distributed environment.Search API Introduction to Enterprise Vault indexing Introduction to Enterprise Vault indexing Index Servers create and manage the indexes for archived data. 439 . Figure 7-1 Standalone Index Server Enterprise Vault server 1 Storage service Index Server Server 1 index locations Vault stores Index Server groups provide load-balanced indexing services for large or distributed Enterprise Vault environments. depending on how the administrator has configured indexing. The Index Servers in a group share the task of indexing the items stored in the archives in the vault stores assigned to the group. ■ Assigns physical index locations to each Index Server. . or an Index Server group. ■ Assigns each vault store to either a standalone Index Server.440 Search API Introduction to Enterprise Vault indexing Figure 7-2 Enterprise Vault server 1 (storage only) Journal vault stores Enterprise Vault server 2 (storage only) Journal vault stores Enterprise Vault server 3 (storage only) Mailbox vault stores Index Server groups in a distributed environment Journal index group Enterprise Vault server 5 (Indexing only) Server 5 index locations Index Server Enterprise Vault server 6 (Indexing only) Server 6 index locations Index Server Mailbox index group Enterprise Vault server 7 (Indexing only) Server 7 index locations Index Server Enterprise Vault server 4 (storage only) Mailbox vault stores Enterprise Vault server 8 (Indexing only) Server 8 index locations Index Server Using the Enterprise Vault Administration Console. and add to each group Index Servers on different Enterprise Vault servers. the administrator performs the following tasks: ■ Creates Index Server groups. not on the archive itself. 441 . Each index volume is contained within an index volume set. the index volumes for an archive may be distributed across multiple Index Servers and locations. The location selected for new index volumes depends on whether the vault store is managed by a single Index Server or an Index Server group. Each index volume contains index entries for the items stored in the archive. Indexes for larger archives. An index volume set contains only one index volume. If the vault store is indexed by an Index Server group. When a user or application performs a search on an archive. new volumes are distributed evenly across the Index Servers and index locations. When an index volume is full. the existing Index Server is used.Search API Introduction to Enterprise Vault indexing About index volumes The index for an archive comprises one or more sequential index volumes. to balance the load across all index locations. For larger archives. if possible. The index location is selected using a round robin algorithm. a user mailbox index requires only one or two volumes. the Index Server automatically creates a new index volume (in a new index volume set). are likely to have multiple volumes. such as file system archives and journal archives. such as journal archives. Typically. as shown in Figure 7-3. the search is performed on index volumes associated with the archive. In general. when the index for a mailbox rolls over. With brief indexing. Created Date. and also provides content searching. Retention Category and so on. ■ Full indexing.442 Search API Introduction to Enterprise Vault indexing Figure 7-3 Spread of index volumes in an Index Server group Journal index group Server 5 index locations containing index volumes Enterprise Vault server 1 Journal vault stores Archive A Archive A index index volume 1 volume 2 Journal archive A Archive A Archive B index index volume 3 volume 1 Enterprise Vault server 2 Journal vault stores Server 6 index locations containing index volumes Journal archive B Archive A index volume 4 Archive B index volume 2 Archive A index volume 5 Archive B index volume 3 About indexing options In Enterprise Vault. you can set the required level of indexing. the content of the item is not indexed. This enables users to search on attributes of an archived item such as Author. different levels can be set for different groups of users. Subject. There are two levels of indexing: brief and full: ■ Brief indexing. . If required. File Extension. Recipients. This enables users to search as for brief indexing. ■ In the Domino Filtering API and File System Filtering API. See “IArchiveMetaData :: IndexData” on page 236. use the method IArchivingControl4 :: AddIndexedPropertyEx. you can add custom index metadata properties to the index document for an item. use the methods on the ISimpleIndexMetadata interface. Granularity of search results In Enterprise Vault 10 and later. and when an item is indexed for a particular archive. See “IArchivingControl interface for Exchange filtering” on page 360. See “IArchivingControl interface” on page 402. ■ In the Exchange Filtering API. When an item is indexed. How Enterprise Vault processes sender and recipient details in different types of messages is described in an appendix to this guide. The level of indexing. the more information that is indexed. In addition to the system index properties. there is a single index document for the top-level item 443 . can be controlled using the Content Management API. Custom filtering is available for Exchange Mailbox Archiving Tasks. See “Adding custom index metadata” on page 72.Search API Introduction to Enterprise Vault indexing Obviously. the more disk space is required for the index. Custom index metadata can be added using the Content Management API or the Filtering APIs. About index properties Enterprise Vault indexes a set of system properties for each item. use the Add method in the IndexMetadata class. searches are performed using item granularity. See “System properties” on page 596. See “IArchive :: IndexUrgency” on page 140. The system properties indexed depend on the level of indexing configured when the item is archived. See “About storing and retrieving message items” on page 627. ■ In the Content Management API. See “SimpleIndexMetadata object” on page 256. See “IArchive :: IndexLevel” on page 142. Exchange Public Folder Tasks and Exchange Journaling Tasks. These properties may be required to enable users or third-party applications to search for particular items. With attachment granularity. In Enterprise Vault 9 and earlier releases. and separate index documents were created for each attachment. you could configure Enterprise Vault to use the item granularity schema by configuring the registry setting. and 32-bit indexes where SchemaType registry setting was configured). When a search is performed. such as those performed by Symantec Compliance and Discovery Accelerator products. Even if the search criteria is matched in one or more attachments. In releases before Enterprise Vault 10 the default indexing schema implemented was attachment granularity. Searches for terms that are combined using AND may return more results than were returned with the attachment granularity schema. Searches returned both top-level items and individual attachments. This is because index data for an item and any attachments are stored in the same index document. and only top-level items are returned in the results. the single index entity (containing both top-level items and attachments) is searched. an index document was created for the top-level item (such as a message). this only tended to be configured on large systems that performed very complex searching. this means that the top-level item and attachments are searched as a single item. only the associated top-level item is returned in the results. No indication is given as to which attachment matches the criteria. Results may contain both top-level items and attachments. Searches on index volumes that use different schemas may behave differently. The differences can be summarized as follows: ■ Attachment granularity searches (32-bit indexes only). A search for for "John Doe" AND "Widgets Corp" may return an .444 Search API Introduction to Enterprise Vault indexing and any attachments. Attachments can be accessed from the top-level items. A search for "John Doe" AND "Widgets Corp" will return any items or attachments that contain both "John Doe" and "Widgets Corp" in the same index document. ■ Item granularity searches (64-bit indexes. in the following location: HKEY_LOCAL_MACHINE \SOFTWARE \KVS \Enterprise Vault \Indexing However. each nested message and attachment was stored in a separate index document. Only the top level item is returned when an attachment matches the criteria. SchemaType. Using the Search API For programming notes on using Enterprise Vault APIs with . ■ IndexSearch2 object is used to select an index to search. All the components required for using the Search API are contained in IndexClient. You do this by adding various terms and operations to the query object using the ISearchQuery2 interface properties and methods. You can do this in the usual manner using CoCreateInstance directly (C++). ■ SearchResult object is used to enumerate through the index property values returned for each search hit (search result). See “Performing a search” on page 449. See “Programming notes” on page 56. Searching across indexes that have been created using different granularity schemas is supported on Enterprise Vault 10 and later. and submit a search query to return some search results. ■ IndexVolumeSet object provides properties that expose information about the index volume set. see the "Programming notes" section. See “Constructing a search query” on page 446. the process of using the Search API is as follows ■ Get an instance of the Search Query object.NET managed code. Briefly. ■ Get an instance of the IndexSearch2 object and submit the search by calling the Search method of IndexSearch2 interface. ■ This returns a SearchResults object. which in turn is used get SearchResult object instances for each of the search hits returned in the SearchResults 445 . or indirectly using the new operator (. and "Widgets Corp" in attachment 3. ■ Build the query. and information about code samples in this manual. ■ SearchResults object is used to enumerate through a set of search results. ■ SearchQuery object is used to construct search queries.NET managed code).dll. ■ IndexVolumeSets object enables access to a collection of IndexVolumeSet objects.Search API Using the Search API item which has "John Doe" in attachment 1. (You do not have to obtain or create the SearchResults or SearchResult objects).this must be between 1st January 1970 and 16th May 2001 The query can now be rewritten as follows: Find All emails where Author = ("Fred Bloggs" or "John Smith") and (Subject contains the phrase "Financial Reports") and (Document Date is between "1st January 1970 and 17th May 2001") The property name.this must contain the phrase "Financial Reports" ■ Document Date . In addition to system property names.this must be earlier than 17th May 2001 The words in italics are the operators within the query. Constructing a search query Take for example the following query expressed in words: The email Author is John Doe or Alan Smith. custom properties defined by the user can also be used. these would be the fields or columns in a table): ■ Author ■ Subject ■ Document Date In order to find the correct emails. This query can be broken down into its constituent parts. See “Processing the search results” on page 452. There are three properties (in a SQL query. we need to attach search conditions to each of these properties: ■ Author . Author. would normally be one of the Enterprise Vault system index property names. . for example.446 Search API Using the Search API object.is either John Doe or Alan Smith ■ Subject . and its Document Date is earlier than 17 May 2001. and its Subject contains the phrase "Financial Reports". See “System properties” on page 596. 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 . Different operators can be specified using the Combine. but instead of taking two SearchQuery objects and combining them to create a third. The search query flag determines how to process individual terms added to a search query. All three methods can be used interchangeably. or AddQuery methods: ■ Combine takes two SearchQuery objects. This is done using the AddOp method: AddOp(ESQor. This new query can be used in a further Combine operation to create searches of arbitrary complexity. If SetTerm is used. The first term could be added to the query as follows: AddTerm(IndexPropAUTH. ESQPhrase). it incorporates the second object into the first. it clears out any previous query. ESQBinary) The query is built up using a reverse Polish system. "John Doe". and at different stages in the construction of a single search query. "Alan Smith". you use the AddTerm method of the ISearchQuery interface. Now the above terms need to be combined using the OR operator. the search object scope. ESQPhrase). combined with the specified operator. ■ AddQuery is similar to Combine. The method creates a new search query containing all the terms in both objects. Which approach you use depends solely on your preference. The operator itself can be obtained from the ESearchQueryOperators enumeration. value. AddTerm has the parameters: property. See “ESearchQueryFlags enumeration” on page 458. See “ISearchQuery :: AddOp” on page 478. the operator is applied to the previous x "objects" to create a new one. To start to construct the earlier example query.Search API Using the Search API Any number of terms can be added to a SearchQuery object. Then the second term could be added to the query as follows: AddTerm(IndexPropAUTH. each containing one or more terms and an operator. they are all combined using the AND operator. search query flag. By default. AddOp. 447 . where x is determined by the value of the second parameter to AppOp. ■ AddOp combines one or more of the terms previously added to the SearchQuery object with the specified operator. The search query operator. 1st January 1970. (For example. In the example query. this term could specify a date range to be searched). if a search query is satisfied in an attachment.448 Search API Using the Search API See “ESearchQueryOperators enumeration” on page 459. ■ A separate search is performed using subsequent queries. ESQany) (In reality. 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. This searches top-level items only. 16th May 2001. ESQfilter. ■ 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. words in message subject or content). such as those required by the Enterprise Vault Compliance and Discovery Accelerator products. The second and third parts are the terms being added in this operation): AppOp(ESQand. . The constructed query can be used by the Search method of the IndexSearch2 interface to search the index of an archive. See “ESQfilter searches” on page 448. ESQQternary) The resulting query now represents the original query that was expressed in words. the Subject term and the date range term: AddTerm(IndexPropSubj. the associated top-level item is returned in results. two more terms can now be added. ESQPhrase) AddRange(IndexPropDate. you would use the appropriate DateTime object for the programming language being used). The following summarizes how this operator works: ■ A search is performed using the first query. Only top-level items are returned in results. ESQfilter searches ESQfilter is similar to ESQ but more powerful. (For example. Note that the Options setting of the Search method is ignored if the search uses the operator ESQfilter. This searches both top-level items and attachments. "Financial Results". is a special operator for performing complex searches. plus at least one of "white or blue". that word must be found.com -domain2. For example. the string value being searched for can contain special characters to modify the search behavior. ■ If words are separated by punctuation (the period is preferred. "white blue +green" means find items containing the word "green". ESQphrase). and so on. search for the string "financial hint" using ESQall. When searching indexes created before Enterprise Vault 10. that word must not be found. for example.com" that were not also sent to "domain2. Use this to specify the index to search. words like "and" and "or" have no special meaning in query values (and cannot be given any special meaning). to search for documents containing both "financial" and "hint".Search API Using the Search API This type of search is particularly efficient for compliance or discovery type searches. ■ If a word or sub-phrase is preceded by + (a single plus character). For example. "minimum".com". ■ To search using wildcards.green" is specified with ESQany. but most punctuation has the same effect). Finally. and a question mark (?) to find any single character. none of the above values has any effect. then the search will look for items containing the single word "white" or the phrase "blue green". For example. Special characters in search queries In addition to the search query flags. Performing a search The index is searched using the methods and properties of the IIndexSearch2 interface.com". there must be at least three other characters before a wildcard. "domain1. Before initiating the search. This finds items sent to "domain1. 449 . ■ If a word or sub-phrase is preceded by . ■ If the entire string is being treated as a single phrase anyway (for example. Individual words are normally separated with spaces. For example.(a single minus character). So. they are treated as a sub-phrase. use an asterisk (*) to find zero or more characters. They will be searched for like any other word. if "white blue. The index is identified using the Id of the associated archive. "min*" matches the words "minutes". set requirements for the search and search results using methods and properties of the IIndexSearch2 interface: ■ SelectArchive method. The archive Id is displayed on the advanced properties page. ■ SelectIndexVolumeSet method. Use this to set the required granularity of the search: ■ roItemGranularity. ■ Options property. The output from a search is a pointer to a SearchResults object. This enables you to "page" through the results. such as "for each" in Visual Basic. . See “Searching indexes with multiple volume sets” on page 451.450 Search API Using the Search API You can use the vault store and archive enumeration functionality in the Content Management API to find the target archive. The object provides standard collection support enabling iterative operations on the results in the collection. which provides a structured way to access the results. ■ SortBy property. ■ ■ AdditionalResultsProperties property. double-click the archive to display the properties dialog and click the Advanced tab. Use this to set the required properties to be returned in results. roAttachmentGranularity. See “ESQfilter searches” on page 448. After setting the required properties. The query is passed to this method as a query string. and . startResult and maximumResults to specify the number of results to return at one time. Use the Search method parameters.NET managed code. Both top-level items and attachments are searched. (Use AdditionalResultsProperties in preference to the ResultsPropertySet property). Only top-level items are searched. Use this to specify the required sort order of the results. not attachments. The Id of an archive can also be discovered using the Enterprise Vault Administration Console: ■ In the Enterprise Vault Administration Console. 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. Note that the Options setting is ignored if the search uses the operator ESQfilter. 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. you initiate the search using the Search method. and ensure that the sequence number property is returned in the search results. Searching indexes that are changing during the search It is quite possible that items are being added to. or equal to MaxSearchIndexVolumeSets (default 5). or use SelectIndexVolumeSet to select the index volume set to search. If it is necessary to select a specific volume set then after calling SelectArchive. or removed from. then you can either increase the number to be searched by setting the value of MaxSearchIndexVolumeSets. ■ 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. When using the index sequence number to define the batch of search results to return. 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. ■ When processing a batch of search results. a call to IndexVolumeSets returns a collection of IIndexVolumeSet pointers from which the ID can be obtained.Search API Using the Search API Concurrent searches To optimize performance. 451 . Be aware that increasing these default settings could result in a time out. If this is the case. the highest sequence number in the results should be recorded. and the number of index volumes is less than. the index while a search is being performed. If an archive has more than five index volumes. The size of each batch is defined by the maximumResults parameter of the Search method. we recommend that you use the index sequence number (IndexPropertySNUM) of an item to specify the start of the batch of search results returned. this should be the last one in the batch. applications using multiple search threads should search different archives or index volume sets. do the following: ■ Always order results by increasing sequence number (IndexPropertySNUM). 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). ■ An archive has multiple index volumes. Repeat this until no more results are found. The SearchResults object has several properties. including the following: ■ Count.0. ■ The ItemGranularityOnly index schema was enabled when the index was created. that is. only top-level items are returned in results for these indexes if any of the following are configured: ■ Searching is limited to top-level items using roItemGranularity option in the Search method. the size of the current collection. a search result is not the archived item. Attachments are searched but the associated top-level item is returned in results. Creating multiple index volume sets for testing In a test environment. there are several properties and methods that are only tested when multiple index volume sets exist. In particular. This is the total number of results for the search. an archive typically only has one index volume set because the number of archived items is relatively low. use the Get method of the IItem interface in the ContentManagementAPI.0 or later. . However. (The implementation of ISearchResults2 contains a collection of ISearchResult2 interface pointers). The first result in the collection. ■ The search query includes the ESQfilter operator. See “IItem :: Get” on page 194. To retrieve the archived item. when developing non-federated search applications. You can access the data for each result returned using the methods of ISearchResult2. results may include attachments and top-level items. and the maximum number of results returned in the collection are defined by the startResult and maximumResults parameters to the Search method. When searching indexes created before Enterprise Vault 10. results include top level items only. Remember. Attachments are searched but the associated top-level item is returned in results. the scope for testing is very limited if there is only one index volume set available. This is the number of results in the object.452 Search API Using the Search API See “IndexSearch object” on page 485. When searching indexes created by Enterprise Vault 10. Processing the search results The SearchResults object is a collection of results returned by IndexSearch. However. ■ Total. it is a set of properties containing information about the item. but the retrieved date values defaults to 1 Jan 1970. ■ Retrievable means that the property can be returned in search results. The first method. 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. Enterprise Vault property names are defined as constants in the form IndexPropXXXX. SearchArchive. Items that are indexed with dateTime properties later than 1 Jan 2038 are also returned in the index search results. See “Adding custom index metadata” on page 72. When searching using date search criteria. but the retrieved date values defaults to 1 Jan 2038. Enterprise Vault index properties See “System properties” on page 596. There are Enterprise Vault system properties and custom properties. use the Prop method of the SearchResult class. Custom properties can be referenced using propertySet. specifying the required property as the parameter.Search API Using the Search API To access the properties of each result. Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. or retrievable or both: ■ Searchable means that the property can be used in search queries to find items in the archive index. takes an archive Id and the maximum number of search results as parameters. 453 . When using the Search API.propertyName. with propertySet empty for the global property set. Items that are indexed with dateTime properties earlier than 1 Jan 1970 are returned in the index search results. See “Index Property constants” on page 457. Properties are defined as searchable. Search API example Shown here are two methods that demonstrate a search. 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 date range values that can be returned in search results are limited to the UTC date range 1st January 1970 to 1st January 2038. //First select the archive search. or the specifed Index Volume Set. The search will filter on a range of archived dates.IndexVolumeSets. a phrase in the subject.Identity). is then called. . this second parameter is zero. DoSearch(search. If the search is not a federated search. and the maximum number of search results. DoSearch.SelectArchive(archId). maxSearchResults). //use this count value to see which approach to take if (count > search. } } else { DoSearch(search.MaxSearchIndexVolumeSets) { //do non-federated search foreach (IIndexVolumeSet volSet in volSets) { search. DoSearch takes two parameters: the IndexSearch2 object created in SearchArchive. } The DoSearch method. depending on whether or not the search is a federated search. int maxSearchResults) { IIndexSearch2 search = (IIndexSearch2) new IndexSearch2(). } Marshal.SelectIndexVolumeSet(volSet. void SearchArchive(string archId.Count. long count = volSets.FinalReleaseCOMObject(search). called from "SearchArchive" performs the actual search on the entire archive.454 Search API Using the Search API The second method. greater than zero attachments and the author. //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. 0). ESQand.AdditionalResultsProperties = "date ssid natc subj cont reto recc rbcc". int start = 1. subject. int maxSearchResults) { ISearchQuery2 query = (ISearchQuery2) new SearchQuery2(). TO:recipient.AddOp((int)ESearchQueryOperators. content (first 150 characters only). DateTime dtTo = new DateTime(2007. BCC:recipient.AddRange("natc". However.AddTerm("subj". (int)ESearchQueryFlags. 1.AddTerm("auth".roItemGranularity. search. 1). for the purposes of this example. if (maxSearchResults > 0) search.ESQany). saveset Id. //we are going to search top level items only search.ESQexact).ESQany). DateTime dtFrom = new DateTime(2007. search. dtFrom. 31).ResultsPropertySet = (int)EPropertySet. first set IIndexSearch2::ResultsPropertySet to Empty. void DoSearch(IIndexSearch2 search. they are supplied in the code. "a phrase in the subject". query. //this is the index number into the results from which to start returning the result set 455 .ESQphrase). 12. "joe.psEmpty.SetRange("adat".Options = (int)EOptionsFlags. search. dtTo. query.SortBy = "snum". (int)ESearchQueryFlags. (int)ESearchQueryFlags. query. CC:recipient. (int)ESearchQueryFlags. 0. //As the preferred method is to explicitly state which properties to //retrieve. number of attachments. 4).MaxSearchResultsPerVolumeSet = maxSearchResults. Typically the property values in the query would be supplied using a GUI or a command line. query. 10000. query.user".Search API Using the Search API The retrieved properties are created date. //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. TruncationReason == ETruncationReason. foreach (ISearchResult2 result in results) { DateTime createdDate = (DateTime)result.trNone) { //make sure that date time properties are returned as local //system time not UTC results. switch (tr) { case ETruncationReason.Search(query.DateTimesUTC = false.InSync == true) { if (results.TruncationReason. string subj = (string)result. start.trAdminTimeoutExpired: //do something break. string ssid = (string)result.456 Search API Using the Search API int count = 0. int numAttach = (int)result.trItemsOrContentMissing: //do something break.Prop("rbcc"). string reto = (string)result.trAdminResultLimitExceeded: //do something break. ISearchResults2 results = null.Prop("ssid"). do { results = (ISearchResults2)search.Prop("date").Prop("natc"). if (results.Prop("subj"). . "").Query. string rbcc = (string)result.Prop("reto"). case ETruncationReason. 500. //do something with the results } } else { ETruncationReason tr = (ETruncationReason)results. case ETruncationReason. FinalReleaseCOMObject(results).Show("It is possible that the index was being updated as the search was being carried out". } while (count != 0). case ETruncationReason. } count = results.FinalReleaseCOMObject(query).OK. Marshal.Search API Constants and enumerations case ETruncationReason. } } } else { MessageBox.trWidthNormalizationRequired: //do something break. case ETruncationReason. start += 500. Index Property constants When using the Search API. "Index not synchronised?". } Constants and enumerations This section describes the constants and enumerations used by the Search API.trTimeoutExpired: //do something break.trNotSearchedOrFailedVolumes: //do something break. Marshal. case ETruncationReason. where IndexPropXXXX is the constant for the property name. MessageBoxButtons. Enterprise Vault property names are defined as constants. MessageBoxIcon.Count. results = null.trResultLimitExceeded: //do something break.Warning). xxxx. See Table A-1 on page 596. 457 . in order (a phrase) ESQexact = 7. // Contains all the words ESQallnear = 2. // Contains any of the words ESQall = 1. using AddTerm). in order ESQmatchmask = 15. // Field exactly matches all the words. IndexPropSUBJ is the constant for the Enterprise Vault defined property. // Contains all the words. 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. // Use words for results ranking ESQutcdate =128. // Contains all the words. //Datetime should be interpreted as UTC rather than local .0.458 Search API Constants and enumerations For example. "rcat". "subj".0 or earlier will continue to be supported. and IndexPropRCAT is the constant for the Enterprise Vault system property. Note: From Enterprise Vault 10. near each other (within 10 words) ESQphrase = 3. enum ESearchQueryFlags { // Exactly one of these must be present (default is ESQany) ESQany = 0. ESearchQueryFlags enumeration ESearchQueryFlags specify how to process individual terms added to a search query (for example. // Mask to isolate above values from flags below // Zero or more of the following may be present ESQrank = 64. = 1048575 // User must not set bits outside this mask By default. ESearchQueryOperators enumeration ESearchQueryOperators specify the operator to use. indexes are built so that they do not support case sensitive searching. Combine and AddQuery methods. Using ESQfilter will only return hits on top-level documents. ESQandnot = 2. ESearchOperatorScope enumeration ESearchOperatorScope defines the number of operands on which an operation is to be performed. and replaced with the result of combining all the terms with the specified operator. ESQscopeall = 1.Search API Constants and enumerations ESQusermask }. using a Reverse Polish scheme. ESQbinary = 2. The search finds items that match the first query and which also match. ESQternary = 3 }. or have a cover note or attachment that matches. These operators can be used with the AddOp. This is to minimize the index storage footprint. all the other queries. The ESearchOperatorScope is a useful extension to the "Reverse Polish" scheme used by the AddOp method. ESQfilter = 3 }. enum ESearchQueryOperators { ESQand = 0. ESQor = 1. The specified operator applies to the terms or ranges already present in the object. Conceptually. the specified number of terms is removed from the query. If no value is given. enabling a single operator to have more than two 459 . This result can then be combined with other terms or intermediate results by a subsequent AddOp method. enum ESearchOperatorScope { ESQdefault = 0. the default is for the operator to be binary (two operands). psAESPS = 6. See “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 518. psWAFull = 3. . both top-level items and attachments are searched. Using roAttachmentGranularity. 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.// default roAttachmentGranularity = 0x00000001. Using roItemGranularity. This setting is ignored if the search uses the operator ESQfilter. EPropertySets enumeration EPropertySets are the predefined property sets that can be requested in search results. there are no symbolic constants. EOptionsFlags enumeration EOptionsFlags defines the granularity of searches. }. Note the value of the scope is the number of operands. psWABrief = 1. when thinking of conventional binary operators. would be one less than the number of operands). enum EPropertySets { psEmpty = 0. default psWAMedium = 2.460 Search API Constants and enumerations operands. so the required number should be specified. only top-level items are searched (not attachments). See “IIndexSearch2 :: AddAdditionalResultsProperty” on page 517. enum EOptionsFlags { roItemGranularity = 0x00000000. For more than three operands. psAEMailbox = 4. not the number of operations (which. psAEFSA = 5. they could be. trTimeoutExpired = 2. trItemsOrContentMissing indicates that index entries are missing for items or content in archive. offline or corrupt. trNotSearchedOrFailedVolumes = 16.symantec. trResultLimitExceeded = 1. trAdminTimeoutExpired = 8. This can occur when one or more of the index volume sets are in a failed state. psCompliance = 8. The index contents for the whole archive cannot be listed.Search API Constants and enumerations psAEMultiFolders = 7. trItemsOrContentMissing = 32.com/docs/TECH52355.// Min set of ids needed to retrieve the item. ETruncationReason enumeration ETruncationReason explains why not all search results have been returned. enum ETruncationReason { trNone = 0. for example. psItemIds = 9. trNotSearchedOrFailedVolumes applies to federated searches only. psAESharePoint = 13 }. psAEShared = 10. Currently there is only one value: enum EXMLResultsFormatOptions { 461 . trWidthNormalizationRequired = 64 }. See http://www. EXMLResultsFormatOptions enumeration EXMLResultsFormatOptions enumerates the XML format option values. trAdminResultLimitExceeded = 4. psAEJournal = 11. psAEPublicFolder = 12. trWidthNormalizationRequired is set for old indexes where character width normalization was not applied to East Asian languages. . which inherits from ISearchQuery. as this is marked as the default. Table 7-2 SearchQuery methods Method Description ISearchQuery :: Clear Discards the query currently being constructed in the object (if any). ISearchQuery :: SetTerm Implements Clear. ISearchQuery :: AddRange Adds a date or integer range to the query. and resets the object so that it is ready for a new query.462 Search API SearchQuery object xoNone = 0x00000000// default }. Some additional methods have been introduced in ISearchQuery2. ISearchQuery :: AddTerm Adds a search term to the query. ISearchQuery :: SetRange Implements Clear followed by AddRange. You need to get a pointer to an instance of ISearchQuery2. followed by AddTerm. SearchQuery object The SearchQuery object implements the following interfaces: ■ ISearchQuery ■ ISearchQuery2 (default) These interfaces are used to build up a search query. Syntax interface ISearchQuery2 : ISearchQuery : IDispatch Member summary Table 7-1 SearchQuery properties Property Read/Write Description ISearchQuery :: Query Read/Write The search query string. ISearchQuery :: Combine Combines two search queries with an operator. and return the values of specified properties as results. Hints and tips on adding custom index properties are provided in the introduction to the Content Management API.Search API SearchQuery object Table 7-2 SearchQuery methods (continued) Method Description ISearchQuery :: SetProperty Implements Clear followed by AddProperty. See “Adding custom index metadata” on page 72. Requirements See “Programming notes” on page 56. ISearchQuery :: AddProperty Adds a property to the query. they can be used by scripting languages. ISearchQuery :: AddOp Adds an operation to the query. or to be set using a text string. Enables use of date AddPropertyRange and integer ranges for custom properties in queries. but combines a query with the query already in the object. Use the methods to create a query that can be used to search the index of an archive. Remarks As these interfaces are ultimately derived from IDispatch. 463 . There are restrictions on the date range that can be returned in search results. ISearchQuery :: AddQuery Similar to combine. Enables use of date and integer ranges SetPropertyRange for custom properties in queries. ISearchQuery2 :: Custom property equivalent of AddRange method. See “Enterprise Vault index properties” on page 453. 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). A query consists of a number of terms. ISearchQuery2 :: Equivalent of SetRange method. dll . //rest of the class ISearchQuery :: Query The Query property is the default property.NET Primary Interop Assembly (PIA) KVS. retval] BSTR* pbsQuery). .EnterpriseVault.Interop Example The object "query" constructed here will be used in the most of the following examples. retval] BSTR* pbsQuery Pointer to a string (BSTR) that will contain the query held in this object.dll . The property is read/write. It is shown here as a private class data member.Indexclient. [C#] public class SampleSearchClass { private ISearchQuery2 query = (ISearchQuery2) new SearchQuery().EnterpriseVault.Interop.464 Search API ISearchQuery :: Query CLSID B94D399B-B815-11D1-90D2-0000F87A3B5E Prog ID EnterpriseVault. Syntax HRESULT Query([out.NET PIA namespace KVS. HRESULT Query([in] BSTR bsQuery).IndexSearch Type Library EVIndexClient DLL IndexClient. Parameters [out. It returns a string containing the query previously constructed. Remarks Clears out the string containing the query that has been constructed so far. 100. Parameters [out. ISearchQuery :: Clear This method discards the query currently being constructed in the object (if any). retval] BSTR* pbsQuery). string] BSTR bsQuery String (BSTR) containing the query with which to initialize the object. Example This method is often used in conjunction with IIndexSearch2::Search where it provides the value for the first parameter. Syntax HRESULT Clear([out.Search(query. Remarks This property returns the query string that has been constructed using the other ISearchQuery2 methods.Query.Search API ISearchQuery :: Clear [in. retval] BSTR* pbsQuery A pointer to a string (BSTR) that contains the contents of the query string before it was cleared out. 1. and resets the object so that it is ready to build a new query. Return value rvS_OK Success. ""). [C#] ISearchResults2 results2 = (ISearchResults2)search. the search query. 465 . retval] BSTR* pbsQuery). [in] VARIANT vVal. . Example In this example the previous query is stored in the string "oldQuery". defaultvalue(0)] const long lFlags. date or integer. [in. reset it and add a new term (property) to the query. [C#] //save the query that is being cleared out string oldQuery = query. string] const BSTR bsProp. This is equivalent to calling the Clear method and then calling the AddTerm method. This can be a string. defaultvalue(0)] const long lFlags Search Query Flags that define how to process the terms added to the search query. string] const BSTR bsProp The name of the property to be searched for. Parameters [in. ISearchQuery :: SetTerm This method is used to clear the current query object. See “ESearchQueryFlags enumeration” on page 458.466 Search API ISearchQuery :: SetTerm Return value rvS_OK Success. [in. Syntax HRESULT SetTerm([in.Clear(). [out. [in] VARIANT vVal VARIANT containing value for which for which to search. In this example the return value is not used.ESQphrase). The parameter lFlags must contain one ESearchQueryFlags enumeration value. retval] BSTR* pbsQuery Remarks If the bsProp parameter is left empty. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. This would be specified using the format: propertySet.Search API ISearchQuery :: SetTerm Pointer to a string (BSTR) that contains the current value of the query string after this method has returned. This value may be bitwise OR'd (C++ operator "|") with one or more values from the extended values. (int)ESearchQueryFlags. 467 . [C#] //search for an item where the subject contains the phrase "some subject" query. [out. "some subject". then the property set name is omitted.propertyName If the custom index property is a member of the global property set. This is really only useful for string values. Example In this example a query is constructed that will find all items where the subject contains the phrase "some subject". then all indexed properties are searched for the value. Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. Return value rvS_OK Success. bsProp can be a custom index property that has been added using the Content Management API. See “Adding custom index metadata” on page 72. and the number of attachments is 1. or one of the Filtering APIs.SetTerm("subj". [out. See “ESearchQueryFlags enumeration” on page 458. ISearchQuery :: AddTerm This method is used to add a new term (property) to the query. [in. . (int) ESearchOperatorScope. //now we AND the 2 terms so that both terms must be satisfied before returning a result query. string] const BSTR bsProp. [in] VARIANT vVal. ■ See “System properties” on page 596. defaultvalue(0)] const long lFlags Search Query Flags that define how to process the terms added to the search query.AddOp((int)ESearchQueryOperators. This can be a string.AddTerm("natc".ESQand. Parameters Table 7-3 AddTerm method parameters Parameter Description [in. retval] BSTR* pbsQuery). 1. ■ See “SimpleIndexMetadata object” on page 256. [in. [in] VARIANT vVal VARIANT containing value for which to search. Syntax HRESULT AddTerm([in.ESQdefault). See also ■ See “ISearchQuery :: AddTerm” on page 468. defaultvalue(0)] const long lFlags. date or integer. (int)ESearchQueryFlags. string] const BSTR bsProp The name of the property in which to search for the value.ESQany).468 Search API ISearchQuery :: AddTerm //search for an item with 1 attachment query. This is really only useful for string values. [C#] 469 . a query is constructed that finds all items where the subject contains the phrase "some subject" and the number of attachments is 1. There are restrictions on the date range that can be returned in search results. This would be specified using the format: propertySet. See “Adding custom index metadata” on page 72. The return value is not used. Remarks If the bsProp parameter is left empty. The parameter lFlags must contain one ESearchQueryFlags enumeration value. Example In this example. Return value rvS_OK Success.propertyName If the custom index property is a member of the global property set. then the property set name is omitted. all indexed properties are searched for the value. bsProp can be a custom index property that has been added using the Content Management API. retval] BSTR* pbsQuery Pointer to a string that contains the current value of the query string after this method has returned. or one of the Filtering APIs.Search API ISearchQuery :: AddTerm Table 7-3 AddTerm method parameters (continued) Parameter Description [out. This value may be bitwise or'd (C++ operator "|") with one or more values from the extended values. Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. See “Enterprise Vault index properties” on page 453. This can be date or integer.ESQphrase).AddOp((int)ESearchQueryOperators. //search for an item with 1 attachment query. reset the object and add a date or numeric (integer) range to the query being built in the object. ■ See “ISearchQuery :: SetTerm” on page 466. [in] VARIANT vVal2 The last value in the range. See also ■ See “System properties” on page 596. string] const BSTR bsProp.470 Search API ISearchQuery :: SetRange //search for an item where the subject contains the phrase "some subject" query. //now we AND the two terms so that both terms must be satisfied before returning a result query.AddTerm("natc". (int) ESearchOperatorScope. [in. Syntax HRESULT SetRange([in. (int)ESearchQueryFlags. . [in] VARIANT vVal2. 1.SetTerm("subj". [out. ■ See “SimpleIndexMetadata object” on page 256. (int)ESearchQueryFlags.ESQdefault). This is equivalent to calling Clear then AddRange. "some subject". Parameters [in. [in] VARIANT vVal1. ■ See “ISearchQuery :: AddProperty” on page 476. retval] BSTR* pbsQuery). ISearchQuery :: SetRange This method is used to delete all queries in the query object. [in] VARIANT vVal1 The first value in the range.ESQany).ESQand. defaultvalue(0)] const long lFlags. string] const BSTR bsProp The name of the property in which to search for the value. This can be date or integer. Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query. [out. There are restrictions on the date range that can be returned in search results. If ESearchQueryFlags. retval] BSTR* pbsQuery Pointer to a string that contains the current value of the query string after this method has returned. Remarks vVal1 and vVal2 must be the same type. it is strongly recommended that you set ESearchQueryFlags. See “Adding custom index metadata” on page 72.ESQutcdate is not set. Currently. This method can only be used with date or integer values. See “ESearchQueryFlags enumeration” on page 458. then the property set name is omitted. This would be specified using the format: propertySet. however.ESQutcdate and supply UTC dateTime values. When specifying dateTime values. bsProp can be a custom index property that has been added using the Content Management API. none of the Search Query Flags has any effect on range searches.propertyName If the custom index property is a member of the global property set. dateTime values are treated as local system dateTime. or one of the Filtering APIs.Search API ISearchQuery :: SetRange [in. Return value rvS_OK Success. 471 . See “Enterprise Vault index properties” on page 453. The parameter lFlags must contain one ESearchQueryFlags enumeration value. ESQdefault). [in.ESQutcdate)).ESQor. Parameters [in. See also ■ See “ISearchQuery :: AddRange” on page 472. //search for items with less than 5 attachments query. 1. //OR the 2 terms together so the result set will contain items that fall into one or //the other (or both) ranges query. DateTime to = new DateTime(2008. 59. from. 0. ■ See “SimpleIndexMetadata object” on page 256. . //search for all items archived between 01/01/2008 and 31/10/2008 inclusive DateTime from = new DateTime(2008. Syntax HRESULT AddRange([in.Utc).Utc). (int)ESearchOperatorScope.ESQany | ESearchQueryFlags. AddOp((int)ESearchQueryOperators. query. [in] VARIANT vVal2. 31. 4. defaultvalue(0)] const long lFlags. ■ See “System properties” on page 596. 1. to.472 Search API ISearchQuery :: AddRange Example This example builds a query that will find items archived between 01/01/2008 and 21/10/2008 inclusive. ( int)(ESearchQueryFlags. (int)ESearchQueryFlags. DateTimeKind. 0. 0. string] const BSTR bsProp The name of the property in which to search for the value. [out. [in] VARIANT vVal1 The upper or lower boundary of the range. 0. or that have less than five attachments. retval] BSTR* pbsQuery). 59. This can be date or integer. [in] VARIANT vVal1.ESQany). ISearchQuery :: AddRange This method is used to add a date or numeric integer range to the query being built in the object. DateTimeKind.AddRange("natc". 23. string] const BSTR bsProp. 10.SetRange("adat". This would be specified using the format: propertySet.ESQutcdate and supply UTC dateTime values. however. retval] BSTR* pbsQuery Pointer to a string that contains the current value of the query string after this method has returned. [out. or one of the Filtering APIs. it is strongly recommended that you set ESearchQueryFlags. dateTime values are treated as local system dateTime. The parameter lFlags must contain one ESearchQueryFlags enumeration value. Currently. 473 . then the property set name is omitted. bsProp can be a custom index property that has been added using the Content Management API. vVal1 and vVal2 must be the same type. If ESearchQueryFlags. When specifying dateTime values.propertyName If the custom index property is a member of the global property set. This can be date or integer. See “ESearchQueryFlags enumeration” on page 458.ESQutcdate is not set.Search API ISearchQuery :: AddRange [in] VARIANT vVal2 The upper or lower boundary of the range. There are restrictions on the date range that can be returned in search results. Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. [in. Remarks This method can only be used with date/time or integer values. See “Enterprise Vault index properties” on page 453. none of the Search Query Flags has any effect on range searches. See “Adding custom index metadata” on page 72. defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query. ■ See “System properties” on page 596. (int)ESearchQueryFlags. //search for items with less than 5 attachments query.SetRange("adat". ■ See “SimpleIndexMetadata object” on page 256. See also ■ See “ISearchQuery :: SetRange” on page 470. Syntax HRESULT SetProperty([in.ESQdefault). [in. DateTime to = new DateTime(2008. [C#] //search for all items archived between 01/01/2008 and 31/10/2008 inclusive DateTime from = new DateTime(2008. string] const BSTR bsPropSet. query. (int)ESearchQueryFlags.ESQor. ISearchQuery :: SetProperty This method clears all queries from the query object. 10. retval] BSTR* pbsQuery). to. and adds a custom property that can be used for searching. [in] VARIANT vVal. defaultvalue(0)] const long lFlags. //OR the 2 terms together so the result set will contain items that fall into one //or the other (or both) ranges query. 0. or that have less than five attachments. 1. AddOp((int)ESearchQueryOperators. . resets the object. 1). [in. 31). 4.ESQany). Example This example builds a query that will find items archived between 01/01/2008 and 21/10/2008 inclusive.ESQany).AddRange("natc". This is equivalent to calling Clear then AddProperty.474 Search API ISearchQuery :: SetProperty Return value rvS_OK Success. string] const BSTR bsProp. (int)ESearchOperatorScope. [out. from. [in. has been added to archived items. string] const BSTR bsPropSet Name of the property set. Two queries are constructed in this sample. This can be a string. Remarks Note that SetTerm can also be used to set a term for a custom property using the propertySet. The two queries are combined to form one query that searches for all items where Instrument. [in. [in] VARIANT vVal VARIANT containing value to search for. date or integer. See “ESearchQueryFlags enumeration” on page 458. [out. The second searches for all items where the retention category = ‘Business’.Search API ISearchQuery :: SetProperty Parameters [in.Type = ‘Guitar’. retval] BSTR* pbsQuery Pointer to a string containing the query as it stands after this method returns. belonging to the property set "Instrument". defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query. Example It is assumed that a custom property "Type". it can only be used to add custom properties. Return value rvS_OK Success. but as it requires both a property set and property name.Type is ‘Guitar’ and retention category is not ‘Business’. SetProperty method is very similar to SetTerm. 475 .propertyName format. string] const BSTR bsProp The name of the custom property to search for. the first searches for all queries with the custom property Instrument. Type and that have a retention category that is not //‘Business’ query.476 Search API ISearchQuery :: AddProperty [C#] //search for items with custom property value ‘Guitar’ string qry1 = query.Combine(qry1. ■ See “System properties” on page 596. .ESQexact). string] const BSTR bsPropSet Name of the property set.SetTerm("rcat".ESQandnot). [in. "Business". See also ■ See “ISearchQuery :: SetTerm” on page 466. string] const BSTR bsPropSet. Syntax HRESULT AddProperty([in. defaultvalue(0)] const long lFlags. "Type". [in] VARIANT vVal. qry2. //search for items with a retention category of "Business" string qry2 = query. [in. retval] BSTR* pbsQuery). ■ See “SimpleIndexMetadata object” on page 256. "Guitar".ESQexact). string] const BSTR bsProp The name of the custom property to search for. (int)(ESearchQueryFlags. //combine the 2 queries so that the result set contains items that contain ‘Guitar’ in //the custom property Instrument. string] const BSTR bsProp. [in.SetProperty("Instrument". ■ See “ISearchQuery :: AddProperty” on page 476. (int) ESearchQueryFlags. [out. Parameters [in. (int)ESearchQueryOperators. ISearchQuery :: AddProperty This method adds a custom property to the query being built in the object and which can be used for searching. "Type". "Colour". [in. "Guitar". has been added to archived items as well as a custom property "Colour".Search API ISearchQuery :: AddProperty [in] VARIANT vVal VARIANT containing value for which for which to search. Example In this example we use the return value which holds the current query. The two queries are combined to form one. Return value rvS_OK Success.AddProperty("Instrument". defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query.SetProperty("Instrument". "red". See “ESearchQueryFlags enumeration” on page 458. [C#] //search for items where custom property Instrument. belonging to the property set "Instrument". (int)( ESearchQueryFlags. date or integer. but with both a property set and property name being included as parameters. belonging to the same property set. This means that it can only be used to add custom properties. It is also assumed that a custom property "Type".Colur is ‘Red’. in order to search for all items where Instrument. The example builds two queries. This can be a string. 477 .ESQexact).Colour = "Red" string qry1 = query.Type is ‘Guitar’ and Instrument.Type = ‘Guitar’ string qry2 = query. //search for items with custom property Instrument. The second searches for items where Instrument.Type is ‘Guitar’. 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. [out. the first searches for all items where Instrument. (int)ESearchQueryFlags.ESQexact).Colour is ‘Red’. 478 Search API ISearchQuery :: AddOp //combine the 2 queries so that the result set contains items that contain ‘Guitar’ in //the custom property Instrument. qry2. [out.Type and "red" in Instrument. (int)ESearchQueryOperators. defaultvalue(0)] const long lScope. ■ See “ISearchQuery :: SetProperty” on page 474.ESQand). Parameters [in] const long lOp The operator to use. retval] BSTR* pbsQuery). .Combine(qry1. defaultvalue(0)] const long lScope How the operator is to be applied. [in. where x is the value given in the second parameter.Colour" query. ■ See “System properties” on page 596. [out. Syntax HRESULT AddOp([in] const long lOp. See “ESearchOperatorScope enumeration” on page 459. See also ■ See “ISearchQuery :: AddTerm” on page 468. Remarks This method combines the previous x properties by using the operator defined in the first parameter. retval] BSTR* pbsQuery Pointer to string that will contain the value of the query after this operator has been added. [in. ISearchQuery :: AddOp This method is used to add an operator to the query in order to combine previously defined terms. ■ See “SimpleIndexMetadata object” on page 256. See “ESearchQueryOperators enumeration” on page 459. Search API ISearchQuery :: Combine An example of an operator is AND or OR. This method does not check the validity of the value passed to the first parameter, so an error will only be reported when Search is called. This method can be called successively in order to build up the query. Return value rvS_OK Success. Example In this example, a query is constructed that will search for all items with a subject that contains the phrase "some subject", and one attachment. In this example the return value is not used. [C#] //search for an item where the subject contains the phrase "some subject" 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); 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. 479 480 Search API ISearchQuery :: Combine [in, string] const BSTR bsQuery2 Second query to add. [in] const long lOp The operator to use. See “ESearchQueryOperators enumeration” on page 459. [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. 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’ Search API ISearchQuery :: AddQuery query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot); 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 459. [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. 481 482 Search API ISearchQuery2 :: SetPropertyRange Example In this example it is assumed there is already a populated ISearchQuery object, query2. This example adds a new query string to this existing query. [C#] string qry = query.SetTerm("cont", "-white blue.red", (int)ESearchQueryFlags.ESQany); query2.AddQuery(qry, (int)ESearchQueryOperators.ESQand); 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 Content Management API, or one of the Filtering APIs. See “Adding custom index metadata” on page 72. 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. Search API ISearchQuery2 :: SetPropertyRange [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 458. [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. vVal1 and vVal2 must be the same type. The parameter lFlags must contain one ESearchQueryFlags enumeration value. Currently, none of the Search Query Flags has any effect on range searches. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. 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 ■ See “Adding custom index metadata” on page 72. ■ See “ISearchQuery :: SetRange” on page 470. ■ See “ISearchQuery :: AddRange” on page 472. ■ See “ISearchQuery2 :: AddPropertyRange” on page 484. 483 484 Search API ISearchQuery2 :: AddPropertyRange ■ See “System properties” on page 596. ■ See “SimpleIndexMetadata object” on page 256. 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 Content Management API, or one of the Filtering APIs. See “Adding custom index metadata” on page 72. 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 458. [out, retval] BSTR* pbsQuery Pointer to a string that will contain the query string formed by this method. Search API IndexSearch object Remarks This method can only be used with date or integer values. vVal1 and vVal2 must be the same type. The parameter lFlags must contain one ESearchQueryFlags enumeration value. Currently, however, none of the Search Query Flags has any effect on range searches. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. 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 ■ See “Adding custom index metadata” on page 72. ■ See “ISearchQuery :: SetRange” on page 470. ■ See “ISearchQuery :: AddRange” on page 472. ■ See “ISearchQuery2 :: SetPropertyRange” on page 482. ■ See “System properties” on page 596. ■ See “SimpleIndexMetadata object” on page 256. IndexSearch object IndexSearch object implements the following interface: ■ IIndexSearch2 485 486 Search API IndexSearch object IIndexSearch2 provides properties and methods that can be used to enable the user to search an archive using a query that has been built using the methods of ISearchQuery2. The output from a search is a pointer to an ISearchResults2 interface, the implementation of which contains a collection of ISearchResult2 pointers. Syntax interface IIndexSearch2 : IDispatch Member summary Table 7-4 IndexSearch properties Property Read/Write Description IndexVolumeSets Read only Returns a collection of Index Volume Sets used by the currently selected archive. Options Read/Write Sets or retrieves the current search options. SortBy Read/Write Gets or sets the current properties used to order the returned search results. (None or one index property). ResultsPropertySet Read/Write Gets or sets a predefined list of properties whose values are to be returned as part of the result set. See “EPropertySets enumeration” on page 460. See Remarks below. AdditionalResultsProperties Read/Write A space separated list of properties returned in the search results in addition to those in the selected results property set. Timeout Read/Write Gets or sets the timeout period, in seconds, applied to search requests. ArchiveEntryId Read only Gets the Id of the currently selected archive. Search API IndexSearch object Table 7-4 IndexSearch properties (continued) Property Read/Write Description ArchiveName Read only Gets the name of the currently selected archive. HasFolders Read only Returns true if the currently selected archive contains folders. IndexVolumeSetIdentity Read only Gets the identity of the currently selected index volume set. IndexVolumeIdentity Read only The identity of the currently selected index volume. IndexVolumeSetCount Read only Gets the number of index volume sets for the currently selected archive. MaxSearchIndexVolumeSets Read/Write For federated searches, gets or sets the current maximum number of volume sets to search. The default value is 5. If number of volumes is above this, the search application must select the specific VolumeSet to search. See “IIndexSearch2 :: SelectIndexVolumeSet” on page 508. MaxSearchResultsPerVolumeSet Read/Write Table 7-5 For federated searches only, gets or sets the current value of the maximum number of results to be returned per volume set. Default is 1000. IndexSearch methods Method Description SelectArchive Sets the Id of the archive to be searched. ListIndexVolumeSets Returns as an XML document the index volume set collection for the selected archive. 487 488 Search API IndexSearch object Table 7-5 IndexSearch methods (continued) Method Description SelectIndexVolumeSet Set the Id of the archive's index volume set to search. If an index volume set is not selected, and the number of index volume sets is less than, or equal to, MaxSearchIndexVolumeSets, then a federated search is automatically performed across the index volume sets. If the number of index volume sets is greater than MaxSearchIndexVolumeSets, then the index volume set to search must be selected. SelectIndexVolume This property should not be used. As Enterprise Vault only supports one volume per volume set, use SelectIndexVolumeSet to select a specific index volume to search. See Remarks below. Search Search the selected archive index or selected IndexVolumeSet. SearchToXML Search the selected archive index or selected IndexVolumeSet, and return the results as XML. AddAdditionalResultsProperty Adds a single property to the AdditionalResultsProperties list. This should be used in preference to ResultsPropertySet. AddAdditionalResultsCustomProperty Adds a single custom property to the 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 IIndexSearch2 :: IndexVolumeSets IIndexSearch2 provides a method that returns a collection of index volume sets. This collection is accessed by methods and properties of the returned IIndexVolumeSet pointer. If the number index volume sets is greater than the number set by MaxSearchIndexVolumeSets (5 is the default), then it is necessary to specify the archive Id and also the index volume sets to search, otherwise an error is returned, rvINDEXING_E_TOO_MANY_VOLUMES. Currently, the index volume set is limited to one index volume. However, in a future release, index volume sets may contain more than one index volume. To prevent any confusion, all new applications should use methods and properties that specify index volume sets, as errors could occur if those that refer to index volumes (such as IIndexSearch2 :: IndexVolumeIdentity) are used. See “IIndexSearch2 :: IndexVolumeIdentity” on page 500. Example The object, "search", constructed in this example will be used in most of the subsequent examples. It is shown here as a private class data member. [C#] public class SampleSearchClass { private IIndexSearch2 search = (IIndexSearch2) new IndexSearch2(); //rest of the class See also ■ See “IndexVolumeSets object” on page 519. ■ See “IndexVolumeSet object” on page 527. 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); 489 490 Search API IIndexSearch2 :: Options 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 519. 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.SelectIndexVolumeSet(volSet.Identity); DoSearch(search); } IIndexSearch2 :: Options This property sets or returns search option flags that define the granularity of search results. The property is read/write. Search API IIndexSearch2 :: SortBy Syntax HRESULT Options([in] long options, [out,retval] long* options); Parameters [in] long options EOptionsFlags value defining required granularity of search results. See “EOptionsFlags enumeration” on page 460. [out,retval] long* options Pointer to a long integer that will contain the current value. Remarks Both messages and their attachments are searched, but the granularity of search results (Option) defines whether attachments are returned in search results or only the top-level items. Return value rvS_OK Success. rvE_POINTER An invalid pointer has been received. Example [C#] [in] search.Options = (int)EOptionsFlags.roItemGranularity; [out] EOptionsFlags eof = (EOptionsFlags )search.Options; if (eof == EOptionsFlags.roAttachmentGranularity) { //do something } else //do something else IIndexSearch2 :: SortBy This property is used to order the returned search results. 491 [C#] [in] //sort by archived date descending search. The sort order is normally ascending.retval] BSTR* sortProperties Pointer to a string that will contain the current properties used for sorting.SortBy = "-" + "adat". [out. [out. Syntax HRESULT SortBy([in] BSTR sortProperties. for example: search.492 Search API IIndexSearch2 :: SortBy The property is read/write. in descending order.SortBy = "-" + "adat". Return value rvS_OK Success. but you can reverse the order by preceding the property with a minus sign (-). . Remarks sortProperties can be none or one index property. rvE_POINTER The pointer passed in to receive the current value is invalid. Example This example shows how to sort by archived date. Parameters [in] BSTR sortProperties String containing the properties by which to sort search results.retval] BSTR* sortProperties). [out] string sortBy = search.SortBy. 493 . Parameters [in] long propertySet Long integer containing the EPropertySets value to be set. Remarks As the predefined property sets may change in future releases.Search API IIndexSearch2 :: ResultsPropertySet IIndexSearch2 :: ResultsPropertySet This property can be used to specify a predefined set of properties returned in search results. See “EPropertySets enumeration” on page 460. [out. Syntax HRESULT ResultsPropertySet([in] long propertySet. See Remarks for important comments on using this property. we strongly recommend that you set this property to psEmpty. and use the AdditionalResultsProperties property and/or AddAdditionalResultsProperty and AddAdditionalResultsCustomProperty to set the required properties to be found in the result set. Return value rvS_OK Success. [out. The property is read/write. rvE_POINTER The long pointer passed in to receive the current value is invalid. Example As this property is no longer the recommended way of setting the returned properties.retval] long* propertySet). it is set to "empty".retval] long* propertySet Pointer to a long integer that will receive the current value. rvE_INVALIDARG The value being set is less than 0. ResultPropertySet = (int)EPropertySets. ■ See “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 518.retval] BSTR* propertiesList). [out] if (search. ■ See “IIndexSearch2 :: AddAdditionalResultsProperty” on page 517.494 Search API IIndexSearch2 :: AdditionalResultsProperties [C#] [in] search.ResultPropertySet = 0. Syntax HRESULT AdditionalResultsProperties([in] BSTR propertiesList). The property is read/write. . Parameters [in] BSTR propertiesList String containing a space separated list of properties to be returned in the search results. HRESULT AdditionalResultsProperties([out. [out. IIndexSearch2 :: AdditionalResultsProperties This property is the recommended way to define the properties returned in search results. // (psEmpty) } See also ■ See “IIndexSearch2 :: AdditionalResultsProperties” on page 494. Remarks The properties added must be in the format of a space delimited list.ResultPropertySet != 0) { search.retval] BSTR* propertiesList Pointer to a string that will receive a list of the current properties.psEmpty. rvE_POINTER The string pointer passed in to receive the current value is invalid. It is recommended that the empty ResultPropertySet is selected.ResultPropertySet = (int)EPropertySets. if (props.Search API IIndexSearch2 :: Timeout Properties you define using this property should be in addition to those found in the predefined property sets.AdditionalResultsProperties = "ssid adat natc". See “EPropertySets enumeration” on page 460.Contains("ssid")) { //do something See also ■ See “IIndexSearch2 :: AddAdditionalResultsProperty” on page 517. [out] string props = search. Example Note that as IIndexSearch2::ResultPropertySet is no longer a preferred method.psEmpty. 495 . The property is read/write. it is set "empty" as a precaution. [C#] [in] search. IIndexSearch2 :: Timeout This property defines the timeout period applied to search requests. ■ See “IIndexSearch2 :: ResultsPropertySet” on page 493. ■ See “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 518. Return value rvS_OK Success.AdditionalResultsProperties. //set empty search. } . the timeout period is applied to all search requests.0 or later.retval] long* seconds). [out. rvE_POINTER The new value being set is equal to or less than zero. The default value is 120 seconds. Example [C#] [in][out] if (search. rvE_INVALIDARG The long integer pointer passed in to receive the current value is incorrect. [in] long seconds [out.retval] long* seconds Pointer to a long integer that will receive the current value.0 or earlier.Timeout = 120. Return value rvS_OK Success. For searches on indexes created using Enterprise Vault 10. Remarks For searches on indexes created using Enterprise Vault 9.Timeout < 120) { search.496 Search API IIndexSearch2 :: Timeout Syntax HRESULT Timeout([in] long seconds. Parameters Long integer containing number of seconds to wait before the search times out. the timeout period is only applied to federated search requests (that is. searches across multiple index volume sets). ArchiveEntryId.retval] BSTR* value) Parameters [out. //do something string aeid = search. Example [C#] search. rvS_FALSE The archive has not been selected yet. The property is read only. Return value rvS_OK Success.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"). Syntax HRESULT ArchiveEntryId([out. rvE_POINTER The BSTR pointer passed in to receive the current value is invalid.retval] BSTR* value Pointer to a string that will receive the current value.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. 497 . Remarks This method will only return a valid Id after SelectArchive has been called. IIndexSearch2 :: ArchiveName This property returns the name of the archive that is currently selected for searching. retval] BSTR* value). Return value rvS_OK Success. this will register as true.retval] BSTR* value Pointer to a string that will contain the current value. textBoxArchId. rvE_POINTER The BSTR pointer passed in to receive the current value is invalid. Example [C#] search. rvS_FALSE The archive has not been selected. then the return value will be S_FALSE.ArchiveName.Text = search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"). //display the archive name in a textbox. Remarks This method will only return a valid archive name after SelectArchive has been called. The property is read only. It is therefore advisable to test that the value acquired is as expected. . If tested in one of the C++ SUCCEEDED or FAILED macros. IIndexSearch2 :: HasFolders This property indicates whether the currently selected archive contains a folder structure.498 Search API IIndexSearch2 :: HasFolders Syntax HRESULT ArchiveName([out. Parameters [out. If the archive has not been selected. retval] VARIANT_BOOL* value). Return value rvS_OK Success. Syntax HRESULT IndexVolumeSetIdentity([out. Parameters [out. rvE_POINTER Value is an invalid pointer. 499 .HasFolders == true) { //do something IIndexSearch2 :: IndexVolumeSetIdentity This property identifies the volume set of the index volume to search. Example [C#] search. //do something if (search. Remarks This method will only return a valid result after SelectArchive has been called.Search API IIndexSearch2 :: IndexVolumeSetIdentity Syntax HRESULT HasFolders([out.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"). rvS_FALSE The archive has not been selected.retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive the current value.retval] long* value). The property is read only. Remarks This property will return a valid Id after SelectArchive has been called. //do something long id = search. Example [C#] search. The property is read only. Return value rvS_OK Success. rvS_FALSE Either SelectArchive has not been called. "Multiple Index Volume Sets".SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"). or there is an invalid value for the Index Volume. if (id == -1) MessageBox. .Show("This archive has multiple Index Volume Sets please select one". IIndexSearch2 :: IndexVolumeIdentity This property should not be used: it is currently available for Enterprise Vault internal purposes only.IndexVolumeSetIdentity.retval] long* value). MB_OK). rvE_POINTER The long integer pointer passed in to receive the current value is invalid. It returns -1 and S_FALSE if SelectArchive has not been called.500 Search API IIndexSearch2 :: IndexVolumeIdentity Parameters [out. or the selected archive has multiple index volume sets and SelectIndexVolumeSet has not been called.retval] long* value Pointer to a long that will receive the current value. Syntax HRESULT IndexVolumeIdentity([out. 501 . Syntax HRESULT IndexVolumeSetCount([out. See “IndexSearch object” on page 485. Return value rvS_OK Success.retval] long* value Pointer to a long integer that will hold the current value. rvS_FALSE The archive Id has not been selected.Search API IIndexSearch2 :: IndexVolumeSetCount Parameters [out. rvE_POINTER Value is an invalid pointer.retval] long* value). The IndexVolumeIdentity is valid (that is. or the internal index volume identity has not been populated (for example. This property returns the IndexVolumeIdentity as selected by the search application. Remarks This property should not be used. in a federated search). Remarks This property should not be used before SelectArchive has been called.retval] long* value Pointer to a long integer that will receive the current value. IIndexSearch2 :: IndexVolumeSetCount This property returns the number of index volume sets in the archive's index. Parameters [out. not 0 or -1) and a valid archive has been selected. The property is read only. 502 Search API IIndexSearch2 :: MaxSearchIndexVolumeSets Return value rvS_OK Success. rvE_POINTER The long integer pointer passed in to receive the current value is invalid. The property is read/write. //carry on with search } else { //do non-federated search } IIndexSearch2 :: MaxSearchIndexVolumeSets This property specifies the maximum number of index volume sets that can be searched by a federated search (that is. Example [C#] search. Syntax HRESULT MaxSearchIndexVolumeSets([out. . a search across multiple index volume sets). long count = search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1"). rvS_FALSE SelectArchive has not been called.IndexVolumeSetCount. //want to do a federated search depending on number of Index Volume sets if (count <= 10) { //do federated search search. retval] LONG* pVal.MaxSearchIndexVolumeSets = count. [in] LONG newVal). IndexVolumeSetCount. Example [C#] search. Return value rvS_OK rvE_INVALIDARG The new value being set is less than 1. Default value is 5.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1"). The default value has been selected to provide a reasonable performance and response times for federated searches. Remarks This property should not be used before SelectArchive has been called. //want to do a federated search depending on number of Index Volume sets if (count <= 10) { //do federated search search. The default is 5. A search that spans multiple index volume sets is called a federated search. //carry on with search } else . [in] LONG newVal Long integer containing the new value to set. long count = search. 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.MaxSearchIndexVolumeSets = count.Search API IIndexSearch2 :: MaxSearchIndexVolumeSets 503 Parameters [out. retval] LONG* pVal Pointer to a long integer that will receive the maximum number of index volume sets that can be searched. rvE_POINTER The long pointer passed in to receive the current value is invalid. In a federated search. a search across multiple index volume sets). The default is 1000 search results per volume set. . The property is read/write. 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. [in] LONG newVal Long integer that sets the new value required. Syntax HRESULT MaxSearchResultsPerVolumeSet([out. rvE_POINTER The long pointer passed in to receive the current value is invalid. Parameters [out. The default value has been selected to provide a reasonable performance and response times for federated searches. Return value rvS_OK rvE_INVALIDARG The new value being set is less than 1. This property indicates the maximum number of search results per volume set that can be processed and merged. results returned from each volume set are processed and merged. retval] LONG* pVal Pointer to a long integer that will receive the current value. retval] LONG* pVal.504 Search API IIndexSearch2 :: MaxSearchResultsPerVolumeSet { //do non-federated search IIndexSearch2 :: MaxSearchResultsPerVolumeSet This property indicates the maximum number of search results that can be returned per volume set by a federated search (that is. [in] LONG newVal). Remarks This property should not be used before SelectArchive has been called. MaxSearchIndexVolumeSets = count. or search the index. //want to do a federated search depending on number of Index Volume sets if (count <= 10) { //do federated search search. The archive must be selected before attempting to list index volume sets associated with the index. //carry on with search } else { //do non-federated search IIndexSearch2 :: SelectArchive This method is used to select an archive to search. long count = search.MaxsearchResultsPerVolumeSet = 500. Parameters [in]BSTR archiveEID String containing the Id of the archive to search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1"). See “Performing a search” on page 449. You can find out the ID of an archive by performing a search. .IndexVolumeSetCount.Search API IIndexSearch2 :: SelectArchive 505 Example [C#] search. Syntax HRESULT SelectArchive([in]BSTR archiveEID). Remarks The SelectArchive method specifies the archive to search in subsequent calls to Search or SearchToXML. search. 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. Syntax HRESULT ListIndexVolumeSets([in] BSTR processingInstruction.506 Search API IIndexSearch2 :: ListIndexVolumeSets Return value rvS_OK Success. DoSearch(search. } See also ■ See “IIndexSearch2 :: Search” on page 511. Example Assume that there is a populated IArchives object. IIndexSearch2 :: ListIndexVolumeSets This method is used to list the index volume set collection for the selected archive as an XML document. 500). [C#] foreach (IArchive archive in archives) { search. rvE_INVALIDARG Either a zero length string has been passed or the archive entry specified could not be found.Id). [out. "archives". ■ See “IIndexSearch2 :: SearchToXML” on page 514.SelectArchive(archive. .retval] BSTR* volumeSetsList). rvE_POINTER The parameter volumeSetList is a NULL pointer. an XSL style sheet reference can be specified with the following string: [in] BSTR processingInstruction xml-stylesheet href="indexvolumesets. Remarks An archive must have been selected using SelectArchive. which can be accessed using the properties and methods of the returned interface pointer.ListIndexVolumeSets("xml-stylesheet 507 . This method is an alternative to using the IndexVolumeSets property. string volSetsXML = search.Search API IIndexSearch2 :: ListIndexVolumeSets Parameters String containing an optional parameter that enables the caller to specify an XML processing instruction. This is added to the XML following the XML declaration. Example [C#] search. IndexVolumeSets returns a pointer to an enumerated collection of IIndexVolumeSet interface pointers. Return value rvS_OK Success. For example.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"). rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set.retval] BSTR* volumeSetsList Pointer to a string that will receive the XML document. [out.xsl" type="text/xsl" (XML processing instruction delimiters are added by the method). since it may represent a new index volume that has not yet been committed to disk. IIndexSearch2 :: SelectIndexVolumeSet This method selects an index volume set when searching an index with multiple index volume sets. all elements except FirstItemSequenceNumber are optional.xsl’ type=‘text/xsl’"). //do something with the XML The following gives an example of the XML returned by the ListIndexVolumeSets method. ■ See “IndexVolumeSets object” on page 519. For the last index volume set. <?xml version="1. .508 Search API IIndexSearch2 :: SelectIndexVolumeSet href=‘indexvolumesets. ■ See “IndexVolumeSet object” on page 527.0" encoding="utf-16" ?> <IndexVolumeSets xmlns="urn:kvsinc-com:EnterpriseVault" ArchiveEntryId="12234E1CE26421C45A096DD3CA06527071110000evsvr" ArchiveName="John Smith" HasFolders="True"> <IndexVolumeSet Identity="20"> <FirstItemSequenceNumber>1</FirstItemSequenceNumber> <OldestArchivedDate>2002-03-13T12:50:38Z</OldestArchivedDate> <YoungestArchivedDate>2004-04-18T06:49:44Z</YoungestArchivedDate> <OldestItemDate>1998-03-26T05:34:02Z</OldestItemDate> <YoungestItemDate>2004-03-02T22:22:23Z</YoungestItemDate> </IndexVolumeSet> <IndexVolumeSet Identity="29"> <FirstItemSequenceNumber>16666344</FirstItemSequenceNumber> <OldestArchivedDate>2004-04-18T06:49:50Z</OldestArchivedDate> <YoungestArchivedDate>2004-04-25T07:02:44Z</YoungestArchivedDate> <OldestItemDate>2004-03-12T20:12:03Z</OldestItemDate> <YoungestItemDate>2004-03-13T22:06:16Z</YoungestItemDate> </IndexVolumeSet> </IndexVolumeSets> See also ■ See “IIndexSearch2 :: IndexVolumeSets” on page 489. rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET The volume set specified does not exist. However. 509 . 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. See “IIndexSearch2 :: ListIndexVolumeSets” on page 506. Unless this property is set to specify an index volume set to search. rvINDEXING_E_TOO_MANY_VOLUMES. Parameters [in] long volumeSetIdentity Long integer containing the Id of the index volume set. Remarks An archive must have been selected using SelectArchive. otherwise the Search API will return an error. if the number of index volume sets exceeds the number set by MaxSearchIndexVolumeSets (default is 5). this property must be set to determine which index volume set to search. Index volume set Ids can be obtained using the ListIndexVolumeSets method.Search API IIndexSearch2 :: SelectIndexVolumeSet Syntax HRESULT SelectIndexVolumeSet([in] long volumeSetIdentity). rvE_INVALIDARG rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set. then a federated search will be carried out across all index volume sets in the archive. See “IIndexSearch2 :: MaxSearchIndexVolumeSets” on page 502. Return value rvS_OK Success. that index volume set is selected by default. For an index with a single index volume set. IndexVolumeSetCount > search. . Example [C#] search. results = (ISearchResults2)search. Parameters [in] long volumeIdentity Remarks This method should not be used.SelectIndexVolumeSet(volSet. An Index Volume Set is considered the smallest element of an archive's index. } } else results = (ISearchResults2)search.Search(query. if (search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1"). //set up the search ISearchResults2 results = null. foreach (IIndexVolumeSet volSet in volSets) { search.Search(query. 1. 100. 1. Syntax HRESULT SelectIndexVolume([in] long volumeIdentity).510 Search API IIndexSearch2 :: SelectIndexVolume rvINDEXING_E_UNABLE_OFFLINE_VOLUME A volume in the set is known to be offline.Identity). ""). 100. See “IndexSearch object” on page 485. //do the search etc.MaxSearchIndexVolumeSets) { IIndexVolumeSets volSets = (IIndexVolumeSets)search. IIndexSearch2 :: SelectIndexVolume This method is used to select a specific index volume of the archive to search.IndexVolumeSets.Query. The ability to select individual index volumes may be removed in a future release. "").Query. Parameters [in] BSTR bsQuery String containing the query. [in] long startResult. rvE_INVALIDARG An unexpected error has occurred. 511 . [in] BSTR reserved This parameter must be "". See “SearchResults object” on page 536. [in] long maximumResults Long integer containing the maximum number of results to return. 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 IIndexSearch2 :: Search This method submits the search request and returns a search results object. retval] IUnknown** resultsSet). [in] BSTR reserved. This is normally the Query property of a SearchQuery object.Search API IIndexSearch2 :: Search Return value rvS_OK Success. [in] long maximumResults. [out. This can be 1 up to the total number of possible results. [in] long startResult Long integer containing the number of the first result. Syntax HRESULT Search([in] BSTR bsQuery. ■ Otherwise. in order. for those terms where the ESQRank flag was specified in the search term. after sorting.512 Search API IIndexSearch2 :: Search [out. which matches all entries in the index. ■ Otherwise. Results are numbered. On return. if any. rvE_POINTER The pointer to the IUnknown pointer passed is the fourth parameter is invalid. As maximum results will probably be exceeded. rvE_ACCESSDENIED rvE_NOINTERFACE rvE_SERVER_UNAVAILABLE rvINDEXING_SERVER_STOPPING . To ensure a well formed query is passed to this method. See “ESearchQueryFlags enumeration” on page 458. See “Performing a search” on page 449. in order of addition to the index. the resulting IUnknown pointer can be QI'd (or cast) to obtain the required ISearchResults2 pointer. See “SearchQuery object” on page 462. by relevance to the words used in the search query. retval] IUnknown** resultsSet Pointer to an IUnknown pointer. The startResult and maximumResults arguments enable paging through search results. Return value rvS_OK Success. it is unlikely to return all the items in the index. Remarks An empty query causes a full wildcard search. obtain an ISearchQuery2 interface pointer and construct a query using the properties and methods of this interface. Each search starts a new search in the Indexing server. Search results are ordered as follows: ■ Using the index property specified with the SortBy property. 100. ISearchResults2 results = (ISearchResults2)search(query.Search API IIndexSearch2 :: Search 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. [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. 1. ""). has been created and populated. Note the fourth parameter must be "".Query. 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". 513 . For example. [in] long maximumResults Long integer containing the maximum number of results to return. [in] BSTR reserved This parameter must be "". [in] BSTR processingInstruction. xml-stylesheet type="test/xsl" href="results. This can be 1 up to the total number of possible results.xsl" . Parameters [in] BSTR bsQuery String containing the query. ■ See “ESearchQueryFlags enumeration” on page 458.retval] VARIANT* xmlResults).514 Search API IIndexSearch2 :: SearchToXML See also ■ See “SearchQuery object” on page 462. [in] long startResult. this is normally the Query property of a SearchQuery object. IIndexSearch2 :: SearchToXML This method is used to search the selected index volume set or index volume and return the results as XML. Syntax HRESULT SearchToXML([in] BSTR bsQuery. [in] BSTR processingInstruction String containing an XML processing instruction which will be inserted into the returned XML. [in] long maximumResults. [in] long xmlFormatOptions. [in] BSTR reserved. This method is similar to Search. [in] long startResult Long integer containing the number of the first result. [out. but it returns XML not an interface pointer. See “Performing a search” on page 449. by relevance to the words used in the search query. for those terms where the ESQRank flag was specified in the search term. obtain an ISearchQuery2 interface pointer and construct a query using the properties and methods of this interface. rvE_POINTER The pointer to the IUnknown pointer passed is the fifth parameter is invalid. As maximum results will probably be exceeded. it is unlikely to return all the items in the index. Currently the only available value is 0. Remarks EXMLResultsFormatOptions enumerates the XML format option values. See “ESearchQueryFlags enumeration” on page 458. To ensure a well formed query is passed to this method. which matches all entries in the index. Return value rvS_OK Success. ■ Otherwise.retval] VARIANT* xmlResults Pointer to a VARIANT containing the search results. in order. See “SearchQuery object” on page 462. ■ Otherwise.Search API IIndexSearch2 :: SearchToXML [in] long xmlFormatOptions Long integer containing a flag from the EXMLResultsFormatOptions. in order of addition to the index. if any. rvE_ACCESSDENIED 515 . Currently there is only the following default value: xoNone = 0x00000000 An empty query causes a full wildcard search. The startResults and maximumResults arguments enable paging through search results. Search results are ordered as follows: ■ Using the index property specified with the SortBy property. [out. after sorting. Each search starts a new search in the Indexing server. Results are numbered. "query". 1. 100. "".Query. has been created and populated. . "". 0).SearchToXML(query.516 Search API IIndexSearch2 :: SearchToXML 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 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. [C#] //select the archive and set up the search query etc byte[] res = (byte[])search. Using the AdditionalResultsProperty list is now the preferred way of specifying properties required in the results set. rvE_POINTER rvE_INVALIDARG A property name has not been specified Example [C#] search. 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. Return value rvS_OK Success. 517 . Remarks In conjunction with AdditionalResultsProperties.AddAdditionalResultsProperty ("natc"). See also ■ See “IIndexSearch2 :: AdditionalResultsProperties” on page 494. Parameters [in] BSTR propertyName String containing the property to add to the list of properties returned in results.Search API IIndexSearch2 :: AddAdditionalResultsProperty IIndexSearch2 :: AddAdditionalResultsProperty This method is used to add a single property to the AdditionalResultsProperties list. Syntax HRESULT AddAdditionalResultsProperty([in] BSTR propertyName).propertyName format. [in] BSTR propertyName String containing the name of the property. Custom properties can be added at the time of storage using the ISimpleIndexMetadata interface. then the propertySet parameter should be set to NULL. . Example [C#] search.AddAdditionalResultsCustomProperty("custpropset". Remarks If the property is in the global property set. [in] BSTR propertyName). "custpropname").518 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. rvE_POINTER A property name has not been specified. Parameters [in] BSTR propertySet String containing the name of the property set. rvE_INVALIDARG A property name has not been specified. Return value rvS_OK Success. Return value rvS_OK Success.Search API IIndexSearch2 :: Reset See also ■ See “IIndexSearch2 :: AdditionalResultsProperties” on page 494. EventArgs e) { //reset button pressed so reset all object properties to default search.Reset(). IIndexSearch2 :: Reset This method is used to reset the object properties to their default values. Syntax HRESULT Reset(). } 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 519 . Example [C#] private void resetButton_Click(object sender. Remarks This method is used to reset the object properties to their default values. ■ See “SimpleIndexMetadata object” on page 256. or using the enumerator returned by _NewEnum. _NewEnum Returns an enumerator object for the collection of Index Volume Set objects or an Index Volume Set collection. Count The number of index volume sets in the collection.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1"). See also ■ See “IIndexSearch2 :: IndexVolumeSets” on page 489. ArchiveName The name of the archive. 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. This interface pointer is returned by a call to the ListIndexVolumeSets method of IIndexSearch2. . Remarks An index volume set comprises a sequence of index volumes.520 Search API IndexVolumeSets object Member summary Table 7-6 IndexVolumeSets properties Property Description ArchiveEntryId The archive Id of the archive to which the index volume set collection belongs. the order of index volumes is defined by the value of FirstItemSequenceNumber.IndexVolumeSets. The volume sets can be enumerated either using the Item property of IIndexVolumeSets. IIndexVolumeSets volSets = (IIndexVolumeSets)search. [C#] search. Example Note that IIndexSearch2::SelectArchive must be called before using IIndexSearch2::IndexVolumeSets. Item Returns an Index Volume Set object using a 1-based index of the collection. HasFolders Whether the archive contains a folder structure. rvE_POINTER The pointer passed in to receive the current value is invalid. ■ See “IIndexVolumeSet :: FirstItemIndexSequenceNumber” on page 531. ■ See “IIndexVolumeSets :: _NewEnum” on page 524. ■ See “IIndexVolumeSet :: YoungestArchivedDate” on page 532. Return value rvS_OK Success. SelectArchive must be called prior to using this property. ■ See “IIndexVolumeSets :: Item” on page 525. IIndexVolumeSets :: ArchiveEntryId This property returns the archive Id of the archive to which the index volume set belongs.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"). Parameters [out. 521 . Remarks Gets the ArchiveEntryId associated with the current index volume sets. Example [C#] search.retval] BSTR* valuePointer to a string that will hold the currently selected archive Id. Syntax HRESULT ArchiveEntryId([out.retval] BSTR* value).Search API IIndexVolumeSets :: ArchiveEntryId ■ See “IIndexSearch2 :: ListIndexVolumeSets” on page 506. ■ See “IIndexVolumeSet :: OldestArchivedDate” on page 531. The property is read only. IndexVolumeSets. The property is read only. The property is read only.retval] BSTR* value Pointer to a string that will contain current name. IIndexVolumeSets :: ArchiveName This property returns the name of the archive to which the index volume set belongs.ArchiveName.retval] BSTR* value). IIndexVolumeSets volSets = (IIndexVolumeSets)search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1"). Syntax HRESULT ArchiveName([out.IndexVolumeSets. string aeid = volSets. . Return value rvS_OK Success. Example [C#] search.522 Search API IIndexVolumeSets :: ArchiveName IIndexVolumeSets volSets = (IIndexVolumeSets)search.ArchiveEntryId. IIndexVolumeSets :: HasFolders This property indicates whether the archive contains a folder structure. Remarks SelectArchive must be called prior to using this property. Parameters [out. string archName = volSets. rvE_POINTER The pointer to a string passed to the property is invalid. if (volSets.retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain a true value if the archive contains a folder structure.IndexVolumeSets. IIndexVolumeSets volSets = (IIndexVolumeSets)search. rvE_POINTER The pointer to a string passed in to receive the current value is invalid. Example [C#] search. Remarks SelectArchive must be called prior to using this property.Search API IIndexVolumeSets :: Count 523 Syntax HRESULT HasFolders([out. . Parameters [out.retval] VARIANT_BOOL* value). Syntax HRESULT Count([out. The property is read only. Return value rvS_OK Success.retval] long* value).SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1").HasFolders == true) { //do something IIndexVolumeSets :: Count This property returns the number of index volume sets associated with the currently selected archive. IIndexVolumeSets volSets = (IIndexVolumeSets)search. Return value rvS_OK Success. //do something IIndexVolumeSets :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the collection. . Syntax HRESULT _NewEnum([out.524 Search API IIndexVolumeSets :: _NewEnum Parameters [out.retval] long* value Long pointer to receive the current number of index volume sets for the current archive.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1").IndexVolumeSets. i <= volSets.Item(i). Remarks SelectArchive must be called prior to using this property. Example [C#] search. for (int i = 1. Parameters [out. rvE_POINTER The long integer pointer passed to the parameter to receive the current value is not valid.Count.retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object. i++) { IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.retval] IUnknown** enumerator). This property is hidden in VBScript. based on the index value passed to it. The property is read only. SelectArchive must be called prior to using this property. VBScript. [out. rvE_POINTER The pointer to the IUnknown pointer passed to the property is invalid. IIndexVolumeSets volSets = (IIndexVolumeSets)search. [C#] search.IndexVolumeSets. Return value rvS_OK Success.Search API IIndexVolumeSets :: Item Remarks This property is a standard property used to support enumerating collections.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1").retval] IUnknown** indexVolumeSet). IIndexVolumeSets :: Item This property returns an index volume set instance from the collection. foreach (IIndexVolumeSet volSet in volSets) { //do something See also See “IIndexVolumeSets :: Item” on page 525. Examples The following examples show how to enumerate the Index Volume Sets in an Index Search object. it is automatically used internally when you use the For Eachconstruct in C#. 525 . Syntax HRESULT Item([in] long index. IIndexSearch2::SelectArchive must be called prior to using this property. See “IIndexVolumeSets :: _NewEnum” on page 524.Count. //do something See also ■ See “IndexVolumeSet object” on page 527. IIndexVolumeSets volSets = (IIndexVolumeSets)search. ■ See “IIndexVolumeSets :: _NewEnum” on page 524.526 Search API IIndexVolumeSets :: Item Parameters [in] long index The 1-based index of index volume sets in the collection. i++) IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i).retval] IUnknown** indexVolumeSet Returns an IUnknown interface to the index volume set object.IndexVolumeSets.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"). { i <= volSets. Return value rvS_OK Success. Remarks This property provides an alternative method to _NewEnum for accessing the IIndexVolumeSet pointers contained in the collection. for (int i = 1. rvE_INVALIDARG Example [C#] search. rvE_POINTER The pointer to the IUnknown pointer passed to the property is invalid. [out. . 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. 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. OldestArchivedDate Read only Archived date of oldest item referenced in this index volume set.Search API 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. 527 . IndexVolumeSet pointers can be obtained using the IIndexVolumeSets interface that enables users to iterate through the index volume sets for an archive. 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. Syntax interface IIndexVolumeSet : IDispatch Member summary Table 7-7 IndexVolumeSet properties Property Read/Write Description Identity Read only The Id of the current index volume set. Examples The following C# examples show two ways of obtaining an object of type IIndexVolumeSet. //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 ■ See “IndexVolumeSets object” on page 519. has been obtained. IIndexVolumeSet :: Identity This property returns the Id of the current index volume set. Both ways assume that an object of type IIndexVolumeSets. . "volSets". items are always archived using UTC time.Item(index). See “IndexVolumeSets object” on page 519. DateTimesUTC Read/Write Indicates whether property values of type VT_DATE are returned as UTC or local system time. The property is read only. 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. By default.528 Search API IIndexVolumeSet :: Identity Table 7-7 IndexVolumeSet properties (continued) Property Read/Write Description YoungestItemDate Read only The youngest date property of the items indexed in the index volume set. IIndexVolumeSet volSet = (IIndexVolumeSet)volSets. Search API IIndexVolumeSet :: ArchiveEntryID Syntax HRESULT Identity([out.IndexVolumeSets.retval] BSTR* value Pointer to a string that will contain the current Id.SelectIndexVolumeSet(volSet. 500). Syntax HRESULT ArchiveEntryId([out. DoSearch(search. Parameters [out. Parameters [out.retval] LONG* value). 529 . } IIndexVolumeSet :: ArchiveEntryID This property returns the archive Id of the archive to which the index volume set collection belongs. Return value rvS_OK Success.Identity). The property is read only. Example [C#] IIndexVolumeSets volSets = (IIndexVolumeSets) search. rvE_POINTER The long integer pointer passed into the property is invalid.retval] LONG* value Pointer to a long integer which will receive the current value. foreach (IIndexVolumeSet volSet in volSets) { search.retval] BSTR* value). Syntax HRESULT ArchiveName([out.retval] BSTR* value).ArchiveEntryId. Return value rvS_OK Success. Parameters [out.530 Search API IIndexVolumeSet :: ArchiveName Return value rvS_OK Success. rvE_POINTER Pointer to a string that will contain the current Id.ArchiveName. Example [C#] string archId = volSet. . The property is read only.retval] BSTR* value Pointer to a string that will contain the current Id. rvE_POINTER The string pointer passed into the property is invalid. Example [C#] string archId = volSet. IIndexVolumeSet :: ArchiveName This property returns the name of the archive to which the index volume set collection belongs. In Windows 2000. rvE_POINTER The VARIANT pointer passed to the property is not valid. Remarks The value of this property determines the order of volume sets in the collection. Parameters [out. The property is read only. so variant type will be VT_DECIMAL. The number is returned as a VARIANT and could be either a variant type VT_I4 or VT_I8.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. 531 . VT_I8 is not supported.FirstIndexSequenceNumber. Syntax HRESULT FirstItemIndexSequenceNumber([out. Example [C#] object obj = volSet.retval] VARIANT* value Pointer to a VARIANT that will receive the index number. Return value rvS_OK Success.retval] VARIANT* value). IIndexVolumeSet :: OldestArchivedDate This property returns the oldest archived date of the items indexed in the index volume set. retval] VARIANT* value Pointer to a VARIANT that will receive the youngest archived date in the index volume set.532 Search API IIndexVolumeSet :: YoungestArchivedDate Syntax HRESULT OldestArchivedDate([out. Parameters [out. Remarks This date value is returned as VARIANT.retval] VARIANT* value Pointer to a VARIANT containing the oldest archived date in the index volume set.retval] VARIANT* value). Parameters [out. rvE_POINTER The VARIANT pointer passed to the property is invalid. Syntax HRESULT YoungestArchivedDate([out. The property is read only. DateTime dateTime = (DateTime)obj. Example [C#] object obj = volSet. Return value rvS_OK Success. The variant type will be VT_DATE. .OldestArchivedDate. IIndexVolumeSet :: YoungestArchivedDate This property returns the youngest archived date of the items indexed in the index volume set.retval] VARIANT* value). DateTime dateTime = (DateTime)obj.retval] VARIANT* value Pointer to a VARIANT that will receive the oldest date of items in the index volume set. The property is read only. 533 .YoungestArchivedDate. IIndexVolumeSet :: OldestItemDate This property returns the oldest item in the index. rvE_POINTER The VARIANT pointer passed in to the property is invalid. The variant type will be VT_DATE.retval] VARIANT* value). Return value rvS_OK Success.Search API IIndexVolumeSet :: OldestItemDate Remarks This date value is returned as VARIANT. The variant type will be VT_DATE. Remarks This date value is returned as VARIANT. Parameters [out. Syntax HRESULT OldestItemDate([out. rvE_POINTER The VARIANT pointer passed to the property is invalid. Example [C#] object obj = volSet. Return value rvS_OK Success. rvE_POINTER The VARIANT pointer passed to the property is invalid. IIndexVolumeSet :: YoungestItemDate This property returns the youngest item in the index. Syntax HRESULT YoungestItemDate([out.534 Search API IIndexVolumeSet :: YoungestItemDate Example [C#] object obj = volSet. DateTime dateTime = (DateTime)obj. Example [C#] object obj = volSet.retval] VARIANT* value). Parameters [out. IIndexVolumeSet :: DateTimesUTC This property indicates whether property values of type VT_DATE are returned as UTC or local system time. The property is read only.retval] VARIANT* value Youngest date of items in the index volume set.OldestItemDate. DateTime dateTime = (DateTime)obj. The variant type will be VT_DATE. . Remarks This date value is returned as VARIANT. Return value rvS_OK Success.YoungestItemDate. 31). Parameters [in] VARIANT_BOOL value VARIANT_BOOL containing the new value to set. object obj = volSet.retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive the current value. HRESULT DateTimesUTC([out. DateTime dt = new DateTime(2006. if (dateTime > dt) { //do something } else //do something else } [out] IIndexVolumeSets volSets = (IIndexVolumeSets) 535 . rvE_POINTER The VARIANT_BOOL pointer passed to the property is invalid. DateTime dateTime = (DateTime)obj.YoungestItemDate. Return value rvS_OK Success.Search API IIndexVolumeSet :: DateTimesUTC The property is read/write. Syntax HRESULT DateTimesUTC([in] VARIANT_BOOL value).IndexVolumeSets. foreach (IIndexVolumeSet volSet in volSets) { //make sure we return the datetime in local system time volSet.retval] VARIANT_BOOL* value). Example [C#] [in] IIndexVolumeSets volSets = (IIndexVolumeSets) search. [out. 12.DateTimeUTC = false. which contains the results (as XML) returned from a search.536 Search API SearchResults object search. .DateTimeUTC. ISearchResults::Options Read only Value of the Options property of the IndexSearch2 object used to generate this set of results. ISearchResults::Total Read only Total number of results that matched the search query. foreach (IIndexVolumeSet volSet in volSets) { bool utc = volSet. ISearchResults::Count Read only The number of results in this 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.IndexVolumeSets. Each result is represented by an SearchResult object. ISearchResults::Start Read only Position in the set of results of the first result in this SearchResults object. This defines the granularity of the search results. Syntax interface ISearchResults2 :ISearchResults : IDispatch Member summary Table 7-8 SearchResults properties Property Read/Write Description ISearchResults::Results Read/Write Pointer to the SearchResults object. or by creating it directly and initializing it with a set of pre-existing results. ISearchResults2::LoadResults Write only Loads search results XML from IStream or SAFEARRAY of bytes or a string (BSTR). ISearchResults::_NewEnum Read only Enumeration for iterating through the results. ""). 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. Table 7-9 SearchResults methods Method Read/Write Description ISearchResults::Item Read only Set of results object returned by enumeration.Query. ISearchResults2::DateTimesUTC Read/Write Whether property values of type VT_DATE are returned as UTC or local system time. 100.Search API SearchResults object Table 7-8 SearchResults properties (continued) Property Read/Write Description ISearchResults::SortBy Read only Name of the properties used to order the search results. Example An object of type ISearchResults2 is obtained from a call to IIndexSearch2::Search.Search(query. [C#] ISearchResults2 results = (ISearchResults2)search. or 537 . 1. The property is read/write. Return value rvS_OK Success. 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. [in. retval] BSTR *pbsResults.Results = xmlResults. [in. string] BSTR bsResults String that contains an XML results string to initialize the object. ISearchResults :: Results This property gets or sets an XML text string which represents the results string. Syntax HRESULT Results([out. rvS_FALSE vE_INVALIDARG rvE_NOINTERFACE Example [C#] . string] BSTR bsResults). //assume we have a set of results in xml. retval] BSTR *pbsResults Pointer to a string that will receive the XML results string. Parameters [out.538 Search API ISearchResults :: Results ISearchResults2 results = (ISearchResults2) new SearchResults(). rvE_POINTER The BSTR pointer passed in to the property is invalid. held in the string xmlResults results. [in] //assume that a previous results set has been stored in the string ‘xmlResults’ ISearchResults2 src = (ISearchResults2) new SearchResults(). 1.Results = xmlResults. //get the results in XML string xmlResults = results.Search(query. 100. The property is read only. retval] long *plCount Long integer pointer that will receive the number found.Results. Syntax HRESULT Count([out. rvE_POINTER The long integer pointer passed into the property is invalid. Example The following example gives an alternative approach to using "foreach" to enumerate the results returned. Parameters [out.Query. retval] long *plCount).Search API ISearchResults :: Count [out] ISearchResults2 results = (ISearchResults2)search. ISearchResults :: Count This property returns the number of results found by the Search operation. Remarks The number of results returned in this SearchResults object may differ from the number of results requested. //initialise the new object with some existing results src. Return value rvS_OK Success. 539 . ""). 100.540 Search API ISearchResults :: Total [C#] ISearchResults2 results = (ISearchResults2)search.Search(query. for (int i = 1. 100.Count. 1. rvE_POINTER The long integer pointer passed into the property is invalid.Query. "").Item(i). long total = results. retval] long *plTotal). ""). Syntax HRESULT Total([out. The property is read only. ISearchResults :: Total This property returns the total number of results that matched the search query. 1.Query. . Remarks Total refers to the total number of hits for the query. Parameters [out. int num = results. the number of results (Count). long num = results. retval] long *plTotal Pointer to a long integer that will receive the total. Return value rvS_OK Success. i <= num. This number should be greater than. Example [C#] ISearchResults2 results = (ISearchResults2)search.Total. or equal to.Count. i++) { ISearchResult2 res = (ISearchResult2)results.Search(query. as result of newly archived. indexed and deleted items. Syntax HRESULT Start([out. The property is read only. Note that Total can also change between calls to consecutive searches. Remarks This value can be from 1 to Total. retval] long *plStart Pointer to a long integer that will receive the start position of the first result in this SearchResults object. Example [C#] ISearchResults2 results = 541 . retval] long *plStart). Return value rvS_OK Success.Search API ISearchResults :: Start if (total < num) { //an error has ooccured as the total should be at least equal to the number results returned ISearchResults :: Start This property returns the start position in the entire set of results of the first result in this SearchResults object. Parameters [out. A search application will not know what the value of Total is on the first call to Search. Value can be from 1 to Total. rvE_POINTER The long integer pointer that was passed to the property is invalid. long start = results.roAttachmentGranularity) { //do something . rvE_POINTER The long integer pointer passed into the property is invalid. 100. 1. The property contains search option flags that define the granularity of search results.Options.Query. 100. 1. Syntax HRESULT Options([out.Query. ""). EOptionsFlags eof = (EOptionsFlags )results. Parameters [out.Start. retval] long *plOptions Pointer to a long integer that will receive the value. retval] long *plOptions). ISearchResults :: Options This property returns the value of the Options property of the IndexSearch2 object used to generate this set of results. Example [C#] ISearchResults2 results = (ISearchResults2)search. Remarks This property retrieves the value that indicates the granularity used to generate the set of results.542 Search API ISearchResults :: Options (ISearchResults2)search. See “IIndexSearch2 :: Options” on page 490. if (eof == EOptionsFlags. The property is read only.Search(query.Search(query. ""). Return value rvS_OK Success. 1. retval] BSTR *pbsSortBy Pointer to a string that will receive the current value Remarks See “IIndexSearch2 :: SortBy” on page 491. The property is read only. ""). retval] BSTR *pbsSortBy). string sortBy = results. rvE_POINTER The string pointer passed into the property is invalid. Parameters [out. This property is hidden in VBScript. 100.Search(query. Return value rvS_OK Success.SortBy.Query. Example [C#] ISearchResults2 results = (ISearchResults2)search. 543 . The property is used to order the returned search results. ISearchResults :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the SearchResults collection. Syntax HRESULT SortBy([out.Search API ISearchResults :: SortBy } else //do something else ISearchResults :: SortBy This property returns the value of the SortBy property of the IndexSearch2 object used to generate this set of results. 100. Remarks This property is a standard property used to support enumerating collections. foreach (ISearchResult2 res in results) { //do something . Syntax HRESULT _NewEnum([out. it is automatically used internally when you use the foreachconstruct in C# or VBScript. as shown in the following example.544 Search API ISearchResults :: _NewEnum The property is read only. This property provides an alternative to Item for iterating through the collection. [C#] ISearchResults2 results = (ISearchResults2)search.Search(query. 1.retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.Query. See “ISearchResults :: Item” on page 545.retval] IUnknown** enumerator). Example This property is not normally called explicitly. Parameters [out. it allows the use of "foreach". Return value rvS_OK Success. rvE_POINTER The pointer to the IUnknown pointer passed to the property is invalid. ""). [out. Parameters [in] long lIndex The index number of the result required in the SearchResult collection. See “ISearchResults :: _NewEnum” on page 543. int num = results. rvE_INVALIDARG The value of the first parameter.Query. The value returned is an ISearchResult interface pointer which provides properties and methods to allow the user to extract the results data.Search API ISearchResults :: Item ISearchResults :: Item This method is used to return the specified item in the SearchResult collection object. [out. 1. is either less than 1 or greater than the number of results returned. Return value rvS_OK Success. Example [C#] ISearchResults2 results = (ISearchResults2)search. ""). lIndex. i <= num.Search(query. 100. retval] LPVARIANT pvResult Pointer to a VARIANT that will receive the ISearchResult pointer. retval] LPVARIANT pvResult). i++) 545 . for (int i = 1. Remarks This property can be used in place of the _NewEnum property to iterate through the collection. Syntax HRESULT Item([in] long lIndex. rvE_POINTER The LPVARIANT passed into the method is invalid.Count. See also ■ See “SearchResult object” on page 550. Remarks Typically a false value indicates that the index is currently being updated. The property is read only. Syntax HRESULT InSync([out. rvE_POINTER The VARIANT_BOOL pointer passed in to receive the current value is invalid.InSync.Search(query. ""). ISearchResults2 :: InSync This property indicates whether or not the index is synchronized with the current contents of the archive. bool inSync = results. 100. if (inSync == false) { . Example [C#] ISearchResults2 results = (ISearchResults2)search.retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain the current value.Query.retval] VARIANT_BOOL* value).Item(i). Return value rvS_OK Success. Parameters [out.546 Search API ISearchResults2 :: InSync { ISearchResult2 res = (ISearchResult2)results. 1. MessageBoxButtons. Return value rvS_OK Success. 100. ""). MessageBoxIcon.Search(query. Parameters [out. "Index not synchronised". ETruncationReason tr = (ETruncationReason)results. 1. for incomplete search results. } else //carry on as normal ISearchResults2 :: TruncationReason This property indicates the reason.retval] ETruncationReason* value Pointer to an ETruncationReason enumeration value which contains the reason for truncation.retval] ETruncationReason* value).Search API ISearchResults2 :: TruncationReason MessageBox. if (tr == ETruncationReason. rvE_POINTER The ETruncationReason pointer passed into the property is invalid Example [C#] ISearchResults2 results = (ISearchResults2)search. The property is read only. See “ETruncationReason enumeration” on page 461.trNone) { //carry on processing } 547 . if any. Syntax HRESULT TruncationReason([out.Warning).TruncationReason.Query.OK.Show("It is possible that the index was being updated as the search was being carried out". rvE_POINTER The VARIANT_BOOL pointer passed in to receive the current value is invalid. Return value rvS_OK Success. The property is read/write. Parameters [in] VARIANT_BOOL value VARIANT_BOOL that will set a new value.retval] VARIANT_BOOL* value).trAdminResultLimitExceeded: //handle the problem break. . items are returned as UTC time.548 Search API ISearchResults2 :: DateTimesUTC else { switch (tr) { case ETruncationReason. //and so on for the other reasons ISearchResults2 :: DateTimesUTC This property indicates whether date/time property values are returned as UTC or local system time. case ETruncationReason.retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive the current value. HRESULT DateTimesUTC([out. Syntax HRESULT DateTimesUTC([in] VARIANT_BOOL value). [out. Remarks By default.trAdminTimeoutExpired: //handle the problem break. if (results. "").SearchToXML method.Search(query.Query. 1. consult Symantec support. ""). If possible.DateTimesUTC == true) { //do something ISearchResults2 :: LoadResults This method can be used to load an instance of ISearchResults2 with the XML results returned by the IIndexSearch2. //make sure date/time values are returned in local system time results. 100.Query. The VARIANT may contain an IStream. Remarks For information on the XML schema used to return the search results.DateTimesUTC = false. 1. Syntax HRESULT LoadResults([in] VARIANT rResultsXML). 549 . byte array (SAFEARRAY) or a string (BSTR) containing the XML. Parameters [in] VARIANT rResultsXML VARIANT containing the XML to load.Search API ISearchResults2 :: LoadResults Example [C#] [in] ISearchResults2 results = (ISearchResults2)search. Return value rvS_OK Success. [out] ISearchResults2 results = (ISearchResults2)search. use the SearchResults object rather than processing the XML directly. 100.Search(query. called xmlResults. [C#] ISearchResults2 results = (ISearchResults2) new SearchResults().550 Search API SearchResult object rvE_INVALIDARG The VT TYPE of the VARIANT is incorrect. Syntax interface ISearchResult2 : ISearchResult : IDispatch Member summary Table 7-10 SearchResult properties Property Read/Write Description ISearchResult::Result Read/Write Gets or sets an XML string containing the search result. ISearchResult2::Count Read Returns the number of properties in this search result. ISearchResult::Number Read only Returns a unique Id for this result. ISearchResult2::DateTimesUTC Read/Write Gets or sets the value of the DateTimesUTC setting. Example In this example. results. rvS_FALSE The XML is empty or the VT TYPE is VT_EMPTY.LoadResults(xmlResults). . it is assumed that there is a string holding a set of XML results from a previous search. 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. Examples The following examples show two different ways of iterating through results in a SearchResults collection object. obtained from a search. [in. ISearchResult2::Item Gets the property at the 1-based position in the collection. or by using ISearchResults::Item to obtain a specific pointer from the collection. 551 . It is assumed there is an ISearchResults2 object. retval] BSTR *pbsResult.Item(index). "results". Remarks ISearchResult interface pointers are obtained by using either ISearchResults::_NewEnum and iterating through the collection. ISearchResult::Prop2 Obtains the value of a specific custom property from the result. string] BSTR bsResult).Search API ISearchResult :: Result Table 7-11 SearchResult methods Method Description ISearchResult::Prop Obtains the value of a specific property from the result. //index is a ‘1’ based index into the collection of ISearchResult's. [C#] ISearchResult2 res = (ISearchResult2)results. Syntax HRESULT Result([out. or foreach (ISearchResult2 res in results) { ISearchResult :: Result This property is used to get an XML string for this result or to set a new XML string. Search(query. //do something ISearchResult :: Number This property returns the unique identifier for this result. 100. rvE_POINTER The string pointer passed in to receive the current value is invalid. 1. Any previous result will be overwritten. [in. It can also be used to store an XML result. string] BSTR bsResult String that contains a new XML string to set.Result. foreach (ISearchResult2 res in results) { string xmlResult = res. retval] long *plNumber). Remarks This property is simply the XML string for the search result stored in this result object. retval] BSTR *pbsResult Pointer to a string that will contain the current string. Return value rvS_OK Success. rvS_FALSE The XML string passed in is zero length. or an empty string if the object is not initialized. Example [C#] ISearchResults2 results = (ISearchResults2)search. Syntax HRESULT Number([out. . "").Query.552 Search API ISearchResult :: Number Parameters [out. The Id is stored in the NUMBER attribute of each XML result tag.Number. foreach (ISearchResult2 res in results) { long number = res. retval] LPVARIANT pvVal). string] BSTR bsName. ""). retval] LPVARIANT pvVal Pointer to a VARIANT that will contain the property value. string] BSTR bsName String containing the name of the property. Return value rvS_OK Success. ISearchResult :: Prop This method returns the specified property for the current result.Search(query. 553 . Example [C#] ISearchResults2 results = (ISearchResults2)search. retval] long *plNumber Pointer to a long integer that will contain the number. Remarks Returns the unique identifier for this result within the collection. Syntax HRESULT Prop([in. rvE_POINTER The long integer pointer passed in to retrieve the value is invalid. [out.Search API ISearchResult :: Prop Parameters [out.Query. 100. 1. Parameters [in. [out. . ISearchResult :: Prop2 This method is used to get the value of a specific custom property.propertyName format. in the propertySet. string or integer.Search(query. VT_DECIMAL. [in] BSTR bsPropertySet. [in] BSTR bsPropertyName. VT_I8. string ssid = (string)obj. ""). string or integer value. the returned VARIANT is an array of VARIANTS. foreach (ISearchResult2 res in results) { object obj = res. Example [C#] ISearchResults2 results = (ISearchResults2)search. VT_UI4.Prop("ssid"). The name can be that of a custom property. If the value is multi-valued. 100. VT_BSTR or VT_EMPTY. retval] LPVARIANT pvVal). RetrieveItem(ssid). [out. rvS_FALSE Property not found. Syntax HRESULT Prop2([in] BSTR bsName.Query.554 Search API ISearchResult :: Prop2 Remarks The value returned can be either a date. Return value rvS_OK Success. rvE_POINTER The VARIANT point passed in to receive the property value is invalid. VT_DATE. The following VARIANT types may be returned: VT_I4. 1. each of which contains a date. The value returned can be either a date. which has an integer property. Example This example assumes there is a custom property set. //the prop we want should be an int but make sure 555 . each of which contains a date. VT_DATE. foreach (ISearchResult2 res in results) { int tag = 0.Search(query. retval] LPVARIANT pvVal Pointer to a VARIANT that will receive the value of the property. VT_DECIMAL. Return value rvS_OK Success. rvE_POINTER The VARIANT pointer passed in to receive the value is invalid. If the requested property does not exist. rvS_FALSE The custom property could not be found. string or integer. "Importance". VT_UI4. "CustomTags". string or integer value. Remarks This method returns the value of a custom property. [in] BSTR bsPropertySet String containing the name of the property set to which the property belongs. VT_I8. an initialized but empty VARIANT will be returned.Query. the returned VARIANT is an array of VARIANTS.Search API ISearchResult :: Prop2 Parameters [in] BSTR bsName This parameter is not currently used. The following VARIANT types may be returned: VT_I4. 100. [C#] ISearchResults2 results = (ISearchResults2)search. [out. ""). [in] BSTR bsPropertyName String containing the name of the property. VT_BSTR or VT_EMPTY. 1. If the value is multi-valued. retval] long* count Long pointer that will receive the number of properties in search result. ISearchResult2 :: Count This property returns the number of properties in the current search result. "Importance"). rvE_POINTER The long integer pointer passed into receive the count number is invalid. Example [C#] ISearchResults2 results = (ISearchResults2)search. i < = count.556 Search API ISearchResult2 :: Count object obj = res. i++) { object objProp = null.Query. out objVal). ""). Syntax HRESULT Count([out. retval] long* count). 100. 1. Return value rvS_OK Success. Type type = obj.Prop2("CustomTags". res. object objVal = null.Name == "Int32") { tag = (int)obj.Search(query.Item(i. if ((string)objProp == "ssid") .GetType(). out objProp. foreach (ISearchResult2 res in results) { int count = res. for (int i = 1. Parameters [out. if (type. The property is read only.Count. Remarks Use this method to obtain the name and value of a property at a specific position in the collection.propertyName format. Syntax HRESULT Item([in] long index. The value returned can be either a date. VT_BSTR or VT_EMPTY. VT_DATE. each of which contains a date. If the value is multi-valued. VT_UI4. in the propertySet. Return value rvS_OK Success. [out] LPVARIANT propertyValue). string or integer value. The name can be that of a custom property. Note that the collection is 1-based not 0-based. VT_DECIMAL. [out] LPVARIANT propertyValue Pointer to a VARIANT that will contain the value assigned to the property. //do something ISearchResult2 :: Item This method returns the property name and value of the property at the position in the index specified by the first parameter. The following VARIANT types may be returned: VT_I4. VT_I8. Parameters [in] long index The index position of the required property. [out] LPVARIANT propertyName. the returned VARIANT is an array of VARIANTS. [out] LPVARIANT propertyName Pointer to a VARIANT that contains the name of the property. 557 .Search API ISearchResult2 :: Item { string ssid = (string)objVal. string or integer. Syntax HRESULT DateTimesUTC([in] VARIANT_BOOL value. out objProp. . 100. //do something ISearchResult2 :: DateTimesUTC This property indicates whether property values of type VT_DATE are returned as UTC or local system time.558 Search API ISearchResult2 :: DateTimesUTC rvE_POINTER One of the VARIANT pointers passed to the method is invalid. [out. [out.Search(query. res. Example [C#] ISearchResults2 results = (ISearchResults2)search. foreach (ISearchResult2 res in results) { int count = res. i < = count.Count. Parameters [in] VARIANT_BOOL value VARIANT_BOOL containing the new value to set.Query. 1. object objVal = null. for (int i = 1.Item(i. rvE_INVALIDARG The index was outside the range 1 to the number of properties. The property is read/write. out objVal). i++) { object objProp = null. if ((string)objProp == "ssid") { string ssid = (string)objVal.retval] VARIANT_BOOL* value). "").retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will receive the current value. Return value rvS_OK Success.Search API ISearchResult2 :: DateTimesUTC Remarks By default. foreach (ISearchResult2 res in results) { bool isUTC = res.DateTimesUTC = false.DateTimesUTC. //do something 559 .Search(query.Query.Search(query. 100. 1. 1. ""). rvE_POINTER Value is an invalid pointer.Query. 100. foreach (ISearchResult2 res in results) { //make sure date/times are returned in local system time res. items are always archived using UTC time. ""). Example [C#] [in] ISearchResults2 results = (ISearchResults2)search. //do something [out] ISearchResults2 results = (ISearchResults2)search. 560 Search API ISearchResult2 :: DateTimesUTC . Chapter Retention API This chapter includes the following topics: ■ About Retention API ■ Retention API ■ Enumerations ■ RetentionCategories object ■ IRetentionCategories :: Count ■ IRetentionCategories :: _NewEnum ■ IRetentionCategories :: Item ■ IRetentionCategories :: DirectoryDNSAlias ■ IRetentionCategories :: Lookup ■ IRetentionCategories :: Create ■ IRetentionCategories :: Add ■ IRetentionCategories :: Update ■ IRetentionCategories2 :: Get ■ RetentionCategory object ■ IRetentionCategory :: Period ■ IRetentionCategory :: Units ■ IRetentionCategory :: IsVisible ■ IRetentionCategory :: Identifier 8 . ■ RetentionCategory The RetentionCategory class maintains a collection of RetentionCategory properties.562 Retention API About Retention API ■ IRetentionCategory :: Name ■ IRetentionCategory :: Description ■ IRetentionCategory :: OnHold ■ IRetentionCategory :: Locked ■ IRetentionCategory2 :: ExpiryBasis About Retention API This chapter describes the Enterprise Vault Retention API and its interfaces. Components The API consists of two apartment-threaded. automation-friendly COM classes: ■ RetentionCategories RetentionCategories implements a collection object of class RetentionCategory. The methods and properties enable the calling application to enumerate the current list of retention categories and add new retention categories. . It implements the IRetentionCategories and IRetentionCategories2 interfaces. ■ Retrieve the details of an existing retention category. ■ Enumerate retention categories. methods and properties. ■ Update an existing retention category. The methods and properties enable the calling application to view and change the various attributes of a retention category. 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. It implements the IRetentionCategory and IRetentionCategory2 interfaces. Retention API The Retention API enables management of the set of Enterprise Vault retention categories. or create a new retention category. The Retention API enables client applications to: ■ Create a new retention category. Years = 3 }. ExpiryBasisModifiedDate = 1. 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". ExpiryBasisUnknown = 3 } . The retention category cannot be saved or updated if the value set is ExpiryBasisUnknown.Retention API Enumerations Security No special privileges are required to list and read retention categories. Retention Units enumeration The RetentionUnits value indicates the type of units used to define the retention period. Retention Date Basis enumeration The RetentionDateBasis value indicates the date from which to calculate the storage expiry date of an item. Months = 2. ExpiryBasisInherit takes the value set for the Enterprise Vault site. Enumerations This section describes enumerations used by the Retention API. ExpiryBasisInherit = 2. Weeks = 1. 563 . enum _RetentionUnits { Days = 0. enum _RetentionDateBasis { ExpiryBasisArchiveDate = 0. Syntax interface IRetentionCategories : IDispatch interface IRetentionCategories2 : IRetentionCategories Member summary Table 8-1 IRetentionCategories properties Property Read/Write Description Count Read only The number of retention categories in the collection. DirectoryDNSAlias Write only Identifies an Enterprise Vault server running an Enterprise Vault Directory Service. _NewEnum Read only An IEnumVariant interface pointer that is used to enumerate the collection of retention categories. Use the Get method to retrieve all properties of a retention category. . Table 8-2 IRetentionCategories methods Method Description Lookup Retrieve limited details of a retention category. as it does not return all available properties. This method is deprecated. and also provides a Get method to retrieve the properties of a retention category.564 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. Item Read/Write This property returns the nth retention category object in the collection. The IRetentionCategories2 interface inherits the properties and methods of the IRetentionCategories interface. RetentionAPI. This is the preferred method for creating a new retention category. Update Update details of an existing retention category.NET PIA namespace KVS. Table 8-3 IRetentionCategories2 method Method Description Get Retrieve details of a retention category.Retention API IRetentionCategories :: Count Table 8-2 IRetentionCategories methods (continued) Method Description Create Create a new retention category.Interop.RententionCategories Type Library RetentionAPILib DLL EVRetentionAPI.Interop IRetentionCategories :: Count This property returns the number of retention categories in the collection.dll . This method is deprecated. The DirectoryDNSAlias property identifies an Enterprise Vault server that can be used to access the Enterprise Vault Directory for retention category information. as it does not enable values to be specified for all available properties. use the Add method to create a new retention category.EnterpriseVault. and the Get method to retrieve details of a retention category.EnterpriseVault. CLSID 744FC7D7-6933-4696-AC3F-9EFC1E00C96B Prog ID EnterpriseVault. Requirements See “Programming notes” on page 56.NET Primary Interop Assembly (PIA) KVS. 565 .dll . Use the Add method Add Add a retention category to the collection. Remarks To ensure all available retention category properties can be retrieved. DirectoryDNSAlias = "EVSite" MsgBox("There are " & oRCs. OnHold=" & oRC.OnHold & " . Parameters [out. Dim Dim Dim Dim oRCs oRC sNames sMsg Set oRCs = CreateObject("EnterpriseVault.566 Retention API IRetentionCategories :: Count The property is read only.Description) else oRCs.Name & " .Count & " categories") For Each oRC In oRCs sMsg = "Category is " & oRC. Locked=" & oRC. retval] long *plCount).RetentionCategories") if Err.Number <> 0 then MsgBox(Err. Syntax HRESULT Count([out. retval] long *plCount Pointer to a long that will contain the current value.IsVisible & " . Return value S_OK Success.Name Next set oRCS = Nothing MsgBox("The list is: " & sNames) end if . E_POINTER The plCount pointer is NULL.Locked MsgBox(sMsg) sNames = sNames & " " & oRC. Example The following Visual Basic script example enumerates the available retention categories. IsVisible=" & oRC. DirectoryDNSAlias = "EVSite" MsgBox("There are " & oRCs. Parameters [out. Return value S_OK Success.retval] IUnknown** enumerator).RetentionCategories") if Err.NET managed code or VBScript. it is automatically used internally when you use the For Eachconstruct in .retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object. Remarks This property is a standard property used to support enumerating collections.Count & " categories") 567 . E_POINTER The pointer to the IUnknown pointer passed to the property is invalid.Number <> 0 then MsgBox(Err. This property is hidden in Visual Basic and Visual Basic Scripting Edition (VBScript). Syntax HRESULT _NewEnum([out. The property is read only. This property returns a collection of RetentionCategory objects.Description) else oRCs. Example Dim Dim Dim Dim oRCs oRC sNames sMsg Set oRCs = CreateObject("EnterpriseVault.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. Syntax propget] HRESULT Item([in] long index. Remarks This method enables an alternative method of enumerating the retention categories in the collection. . The index is 1-based. retval] VARIANT* pVal).Name & " .568 Retention API IRetentionCategories :: Item For Each oRC In oRCs sMsg = "Category is " & oRC. Return value S_OK Success. Parameters [in] long Index Long containing the index value of the required item. IsVisible=" & oRC. Locked=" & oRC.IsVisible & " . [out. retval] VARIANT* pVal Pointer to a VARIANT that will contain the retention category interface pointer requested.OnHold & " .Locked MsgBox(sMsg) sNames = sNames & " " & oRC. The property is read/write. E_INVALIDARG Index is less than or greater than the collection count.Name Next set oRCS = Nothing MsgBox("The list is: " & sNames) end if IRetentionCategories :: Item This property returns the nth retention category object in the collection. E_POINTER pVal is an invalid pointer. [out. OnHold=" & oRC. Item(i + 1). ■ ■ Id of any archive in the Site. Remarks The Id of an Enterprise Vault Site can be found in the following registry entry on an Enterprise Vault server: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS 569 .Retention API IRetentionCategories :: DirectoryDNSAlias Example IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass(). ■ Id of the Enterprise Vault Site. i < retCats. retCats.DirectoryDNSAlias = "SERVER1". i++) { IRetentionCategory retCat = (IRetentionCategory)retcats. ■ IP address of a computer hosting an Enterprise Vault Directory Service. ■ Id of any vault store in the Site.Count. in order to retrieve information from the Enterprise Vault Directory. Parameters [in] BSTR bstrVal The value can be any one of the following: DNS alias of a computer hosting an Enterprise Vault Directory Service. The property is write only. IRetentionCategories :: DirectoryDNSAlias This property is used to identify a computer running an Enterprise Vault Directory Service. Syntax HRESULT DirectoryDNSAlias([in] BSTR bstrVal). for (int i = 0. DirectoryDNSAlias = "ourvaultsite. in the properties dialog for an archive. Example The following example sets a value for DirectoryDNSAlias in order to list retention categories on a remote Enterprise Vault server. Similarly.Count & " categories") For Each oRC In oRCs sMsg = "Category is " & oRC. SiteIdNotFound bstrValue does not identify an existing site.OnHold & ".IsVisible & " .Name Next set oRCS = Nothing . If you do not set DirectoryDNSAlias.570 Retention API IRetentionCategories :: DirectoryDNSAlias \Enterprise Vault \SiteID The Id of an archive can be found in the Enterprise Vault Administration Console.Description) else oRCs.Name & " .Number <> 0 then MsgBox(Err.Locked MsgBox(sMsg) sNames = sNames & " " & oRC. OnHold=" & oRC. Return value S_OK Success. Dim Dim Dim Dim oRCs oRC sNames sMsg Set oRCs = CreateObject("EnterpriseVault.RetentionCategories") if Err. then connection to the local computer is assumed. E_UNEXPECTED An unexpected error has occurred. in the properties dialog for a vault store. Locked=" & oRC. IsVisible=" & oRC.domain.com" MsgBox("There are " & oRCs. the Id of a vault store can be found in the Administration Console. VARIANT* Id. years). we recommend that you use the Get method instead. 571 .[in] BSTR NameOrId String containing name or Id of the retention category. weeks. This is the number of retention units an item is to be retained. months. VARIANT *IsVisible. Identifies the retention category to the end user and the administrator. This is the type of retention units (days. Syntax HRESULT Lookup([in] [out] [out] [out] [out] [out] [out. VARIANT* RCName. VARIANT *Period. retval] VARIANT* RCFound). [out] VARIANT *Period Value of Period for the retention category. Describes whether the retention category is to be displayed to end users. [out] VARIANT *Units Value of Units for the retention category. [out] VARIANT* Id Identifier of the retention category. VARIANT *Units. [out] VARIANT *IsVisible Value of IsVisible for the retention category. Parameters .Retention API IRetentionCategories :: Lookup MsgBox("The list is: " & sNames) end if IRetentionCategories :: Lookup This method is used to obtain details of a retention category when the Name or Id of the retention category is known. [out] VARIANT* RCName Name of the retention category. As this method does not return all available retention category properties. BSTR NameOrId. Lookup "Public". As this method does not allow the specification of all available retention category properties. . period. retval] VARIANT* RCFound A boolean return value that indicates whether or not the lookup was successful. isvisible. isvisible oAPI. we recommend that you use the Add method instead. Syntax HRESULT Create([in] BSTR Name. id. units. Return value S_OK Success. Dim oAPI Dim msg Set oAPI = CreateObject("EnterpriseVault. [in] LONG Period.572 Retention API IRetentionCategories :: Create [out. E_UNEXPECTED An unexpected error has occurred. name. units.RetentionCategories") Dim id. name set oAPI = Nothing msg msg msg msg msg = = = = = msg msg msg msg msg & & & & & " " " " " name = " & name period = " & period units = " & units isvisible = " & isvisible id = " & id Msgbox(msg) IRetentionCategories :: Create This method is used to create a new retention category. Example The following Visual Basic script example looks up the values assigned to the Public retention category. period. [in] BSTR Description Description of the retention category.Retention API IRetentionCategories :: Create [in] RetentionUnits Units. weeks. Parameters [in] BSTR Name The name of the retention category. E_UNEXPECTED An unexpected error has occurred. If IsVisible is false. E_INVALIDARG One of the parameters is incorrect. [in] LONG Period Number of retention units items are to be retained.retval] BSTR* Id). [out. [in] RetentionUnits Units Enumeration value for type of retention units (days. years). See “Retention Units enumeration” on page 563. This method does not allow you to set a specific value for the ExpiryBasis property. RetentionCategoryAlreadyExists A retention category with the same name already exists 573 . Remarks If the value of Period is 999999. months.retval] BSTR* Id Retention category Id. and the value of Units is Years. [out. [in] VARIANT_BOOL IsVisible Determines whether or not the retention category will be available to users for selection in manual archive operations. Return value S_OK Success. the retention category is still visible in the Enterprise Vault Administration Console. the default value for the Enterprise Vault site will be used. [in] BSTR Description. [in] VARIANT_BOOL IsVisible. the retention period is "forever". retCats. RetentionCategoryAlreadyExists A retention category with the same name already exists . RetentionUnits. the retention period is "for ever".10. Parameters . E_NOINTERFACE There is a problem with the IRetentionCategory pointer passed into the method.[in] IUnknown* RetentionCategory A reference to a RetentionCategory object.574 Retention API IRetentionCategories :: Add Example IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass(). Syntax HRESULT Add([in] IUnknown* RetentionCategory). "New business correspondence"). Return value S_OK Success. If the value of Period is 999999. E_INVALIDARG One of the properties of the IRentionCategory pointer is invalid.Months. and the value of Units is Years.Create("New business". E_UNEXPECTED An unexpected error has occurred. Remarks An error will be returned if a retention category already exists with the same name. IRetentionCategories :: Add This is the preferred method for creating a new retention category and adding it to the collection object. false. IsVisible = False oRC.Units = 3 oRC.Name = "Finance" oRC.Locked = False oRCS.Units = 3 oRC.RetentionCategory") oRC.Period = 7 oRC.Description = "For legal department items" oRC.Add(oRC) msgbox(oRC.Description = "For finance dept items" oRC.OnHold = True oRC. Dim oRCS Dim oRC Set oRCS = CreateObject("EnterpriseVault.Name = "Legal" oRC.RetentionCategory") oRC.Add(oRC) msgbox(oRC.Locked = True oRCS.Retention API IRetentionCategories :: Add Example The following Visual Basic script example adds two new retention categories: Finance and Legal.IsVisible = True oRC.OnHold = False oRC.identifier) 'Create another Retention Category Set oRC = Nothing Set oRC = CreateObject("EnterpriseVault.RetentionCategories") 'Create a Retention Category Set oRC = Nothing Set oRC = CreateObject("EnterpriseVault.Period = 6 oRC.identifier) 575 . Example The following example updates details of retention categories on a remote computer and sets all the retention categories on hold. Return value S_OK Success.576 Retention API IRetentionCategories :: Update IRetentionCategories :: Update This method is used to change an existing retention category. Remarks Any changes that you make to a retention category will be retrospective. Syntax HRESULT Update([in] IUnknown* RetentionCategory).Number <> 0 then MsgBox(Err. Parameters . Dim Dim Dim Dim oRCs oRC sNames sMsg Set oRCs = CreateObject("EnterpriseVault.RetentionCategories") if Err. RetentionCategoryNotExist The retention category does not exist. and be applied to unexpired items that have been archived with the retention category. E_INVALIDARG One of the properties of the IRetentionCategory pointer passed as a parameter is invalid.Description) .[in] IUnknown* RetentionCategory Reference to the RetentionCategory object to be updated. An error will be returned if the retention category specified does not exist. E_UNEXPECTED An unexpected error has occurred. It returns a populated instance of the RetentionCategory object.com" MsgBox("There are " & oRCs.OnHold = true oRCs. retval] IUnknown** RetentionCategory). Syntax HRESULT Get([in] BSTR NameOrId. 577 .OnHold & " . Return value S_OK Success. including the ExpiryBasis property.Count & " categories") For Each oRC In oRCs sMsg = "Category is " & oRC. Parameters [in] BSTR NameOrId String containing name or Id of the retention category.Update(oRC) sNames = sNames & " " & oRC.IsVisible & " .DirectoryDNSAlias = "ourvaultsite. E_UNEXPECTED An unexpected error has occurred. [out.Name Next set oRCS = Nothing MsgBox("The list is: " & sNames) end if IRetentionCategories2 :: Get This is the preferred method for obtaining details of a retention category. Remarks This method supersedes the Lookup method as it enables the retrieval of all available retention category properties. E_INVALIDARG NameOrId is NULL or RetentionCategory is NULL. IsVisible=" & oRC.Name & " . OnHold=" & oRC.Retention API IRetentionCategories2 :: Get else oRCs.Locked MsgBox(sMsg) oRC. Locked=" & oRC.domain. RetentionCategory object The RetentionCategory object implements the following interfaces: ■ IRetentionCategory ■ IRetentionCategory2 (default) The interfaces maintain a set of properties for a RetentionCategory object. weeks. . months or years.Get("Business"). The IRetentionCategory2 interface inherits the properties and methods of the IRetentionCategory interface. Identifier read/write This property uniquely identifies the retention category. Syntax interface IRetentionCategory : IDispatch interface IRetentionCategory2 : IRetentionCategory Member summary Table 8-4 IRetentionCategory properties Property Read/Write Description Period read/write This property describes the number of retention units (days. months. and also provides the ExpiryBasis property. Example IRetentionCategories2 retCats2 = (IRetentionCategories2) new RetentionCategoriesClass(). years) an item is to be retained.578 Retention API RetentionCategory object RetentionCategoryNotExist A Retention Category with the given NameOrId value does not exist. IRetentionCategory retcat = (IRetentionCategory)retCats2. Units read/write This property describes whether the period has been expressed in days. weeks. IsVisible read/write This property describes whether the category is to be displayed to end users. Requirements CLSID 333D8892-6804-4090-942B-43909C498951 Prog ID EnterpriseVault. OnHold read/write This property describes whether archived items with a particular retention category can be deleted or expired. IRetentionCategory2 property Table 8-5 Property Read/Write Description ExpiryBasis read/write This property indicates the date from which to calculate the storage expiry date of an item. This prevents an administrator from inadvertently modifying the retention category. 579 . Locked read/write This property enables a lock to be put on a retention category. and also after the retention period has expired. Description read/write This property describes the retention category to the administrator.Retention API IRetentionCategory :: Period IRetentionCategory properties (continued) Table 8-4 Property Read/Write Description Name read/write This property identifies the retention category to the end user and the administrator. or by obtaining one from the collection held in an instance of RetentionCategories.NET or Visual Basic). weeks. months. The property is read/write. This retention category hold is different from the Legal Hold API. This protection applies during the retention period. Remarks A RetentionCategory pointer can either be obtained using CoCreateInstance (or the equivalent in .RetentionCategory IRetentionCategory :: Period This property describes the number of retention units (days. years) an item is to be retained. Name = "Finance".Description = "For finance depts".Period = 10. Remarks If the value of Period is 999999. retcat. retcat. retcat. retcat.DirectoryDNSAlias = "SERVER1".580 Retention API IRetentionCategory :: Period Syntax HRESULT Period([out. E_POINTER pVal is an invalid pointer. . IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass(). E_INVALIDARG newVal is outside the bounds of the permitted range (1 . retcat. retcat.999999) Example [in] IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass(). retCats. and the value of Units is Years.Units = RetentionUnits.IsVisible = true. years) an item is to be retained. retval] long* pVal). Return value S_OK Success. [in] long newVal The range of permitted values is from 1 to 999999 inclusive.Months. retval] long* pVal Reference to the number of retention units (days. Parameters [out. months. weeks.Identifier = "xyz". HRESULT Period([in] long newVal). the retention period is "for ever". months or years. i++) { IRetentionCategory retCat = (IRetentionCategory)retcats.Units.Description.OnHold. HRESULT Units([in] RetentionUnits newVal). string ident = retCat.Identifier. The property is read/write. i < retCats.OnHold = true. bool onHold = retCat. [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass().Name.Count. retCats. retCats.IsVisible. RetentionUnits ru = retCat. for (int i = 0.Item(i + 1).Add(retCat). weeks.Locked = true. string name = retCat. Syntax HRESULT Units([out. Locked.Period.Retention API IRetentionCategory :: Units retcat. retcat.DirectoryDNSAlias = "SERVER1". long period = retCat. bool locked = retCat. IRetentionCategory :: Units This property describes whether the period is expressed in days. string descr = retCat. bool isVis = retCat. retval] RetentionUnits* pVal). 581 . Identifier = "xyz". retCats.OnHold = true.Description = "For finance depts".DirectoryDNSAlias = "SERVER1". retval] RetentionUnits* pVal Enumerated value for type of retention units (days.Locked = true. and the value of Units is Years. Remarks If the value of Period is 999999. Return value S_OK Success.Months. retcat. retcat. retcat. months. years).IsVisible = true. retcat.582 Retention API IRetentionCategory :: Units Parameters [out.Units = RetentionUnits. IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass(). the retention period is "for ever".999999) Example [in] IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass(). [in] RetentionUnits newVal RetentionUnits enumerated value. E_INVALIDARG newVal is outside the bounds of the permitted range (1 .Period = 10. retcat. retcat. weeks.Name = "Finance". E_POINTER pVal is an invalid pointer. See “Retention Units enumeration” on page 563. retcat. retcat. . Description. retval] VARIANT_BOOL* pVal Reference to current value.DirectoryDNSAlias = "SERVER1". locked = retCat.Count. Locked. Parameters [out.Item(i + 1). retval] VARIANT_BOOL* pVal). string descr = retCat. string ident = retCat. [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass(). for (int i = 0. RetentionUnits ru = retCat. retCats. [in] VARIANT_BOOL newVal New value.Units.Retention API IRetentionCategory :: IsVisible retCats. isVis = retCat. long bool bool bool period = retCat.Identifier. Syntax HRESULT IsVisible([out.Name. The property is read/write. onHold = retCat.OnHold.IsVisible. IRetentionCategory :: IsVisible This property describes whether the retention category is to be displayed to end users. i++) { IRetentionCategory retCat = (IRetentionCategory)retcats. i < retCats.Period. HRESULT IsVisible([in] VARIANT_BOOL newVal). 583 .Add(retCat). string name = retCat. even if this the value of this property is FALSE. E_INVALIDARG newVal is outside the bounds of the permitted range (1 .Identifier = "xyz". retcat. retcat. E_POINTER pVal is an invalid pointer. .IsVisible = true. IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass().Description = "For finance depts". retcat. retcat. retCats. retCats. [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass().Add(retCat).999999) Example [in] IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass().OnHold = true.DirectoryDNSAlias = "SERVER1". retcat. Return value S_OK Success.DirectoryDNSAlias = "SERVER1". retCats. retcat.584 Retention API IRetentionCategory :: IsVisible Remarks All retention categories are visible to administrators in the Administration Console. retcat.Name = "Finance". retcat.Locked = true.Units = RetentionUnits.Months.Period = 10. retval] BSTR* pVal Pointer to a string containing the retention category Id. i < retCats.Units. Syntax HRESULT Identifier([out.Item(i + 1).Name.Count. Example [in] IRetentionCategories retcats = (IRetentionCategories) new 585 . RetentionUnits ru = retCat.IsVisible. HRESULT Identifier([in] BSTR newVal). [in] BSTR newVal Return value S_OK Success.Description. bool isVis = retCat. string name = retCat. bool onHold = retCat. bool locked = retCat. The property is read/write. String containing retention category Id (up to 250 Unicode characters). IRetentionCategory :: Identifier This parameter uniquely identifies the retention category. string descr = retCat.Period. retval] BSTR* pVal). Parameters [out. E_POINTER pVal is an invalid pointer.Retention API IRetentionCategory :: Identifier for (int i = 0. i++) { IRetentionCategory retCat = (IRetentionCategory)retcats.Identifier. long period = retCat. Locked.OnHold. string ident = retCat. Locked = true. retcat. string ident = retCat.Period. retcat.Count. retcat.IsVisible = true. retcat.Name. retcat.Description. for (int i = 0. retCats.DirectoryDNSAlias = "SERVER1". .IsVisible.OnHold = true. retcat. long period = retCat.DirectoryDNSAlias = "SERVER1".Identifier = "xyz". i < retCats. retcat.OnHold.Units.Add(retCat). IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass(). bool locked = retCat. retCats.Identifier. i++) { IRetentionCategory retCat = (IRetentionCategory)retcats.Description = "For finance depts". [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass(). Locked. retCats.Months.Item(i + 1). bool onHold = retCat.586 Retention API IRetentionCategory :: Identifier RetentionCategoriesClass(). retcat. string name = retCat.Name = "Finance". string descr = retCat. bool isVis = retCat.Period = 10. RetentionUnits ru = retCat.Units = RetentionUnits. retcat. retval] BSTR* pVal). Syntax HRESULT Name([out. HRESULT Name([in] BSTR newVal). retval] BSTR* pVal The current retention category name.Months. Example [in] IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass(). retCats.Identifier = "xyz".Retention API IRetentionCategory :: Name IRetentionCategory :: Name This parameter identifies the retention category to end users and the administrator. Parameters [out. Return value S_OK Success.DirectoryDNSAlias = "SERVER1".Period = 10. Maximum length is 32 unicode characters. retcat. E_POINTER pVal is an invalid pointer. IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass().Name = "Finance". retcat. The property is read/write. retcat. [in] BSTR newVal New retention category name. 587 .Units = RetentionUnits.Description = "For finance depts". retcat. string name = retCat.Units. bool isVis = retCat.Item(i + 1). retval] BSTR* pVal Pointer to description of retention category. Syntax HRESULT Description([out.Name. long period = retCat. retCats.OnHold.IsVisible. The property is read/write. Locked.Add(retCat). [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass().DirectoryDNSAlias = "SERVER1". retcat.Identifier. i < retCats. IRetentionCategory :: Description This property describes the retention category to the administrator. Parameters [out. i++) { IRetentionCategory retCat = (IRetentionCategory)retcats. .Period. string ident = retCat.Count. retCats. HRESULT Description([in] BSTR newVal).OnHold = true. string descr = retCat. retval] BSTR* pVal). RetentionUnits ru = retCat.Locked = true.Description. bool onHold = retCat.588 Retention API IRetentionCategory :: Description retcat. for (int i = 0.IsVisible = true. retcat. bool locked = retCat. The property is read/write. Remarks When creating a retention category. The value cannot be an empty string. neither users nor Enterprise Vault storage expiry can delete items that have been stored using this retention category. E_INVALIDARG newVal is either an empty string or is greater than 127 characters in length. this property must be set. [in] BSTR newVal Maximum length is 127 unicode characters. This protection applies during the retention period. 589 . and also after the retention period has expired. Parameters [out. Remarks This retention category hold is different from the Legal Hold feature. retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL containing the current value. HRESULT OnHold([in] VARIANT_BOOL newVal). [in] VARIANT_BOOL newVal New value. While this property remains true. E_POINTER pVal is an invalid pointer. IRetentionCategory :: OnHold This property describes whether archived items with a particular retention category can be deleted or expired.Retention API IRetentionCategory :: OnHold New description of retention category. Return value S_OK Success. Syntax HRESULT OnHold([out. retval] VARIANT_BOOL* pVal). Example [in] IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass().Months.Locked = true.DirectoryDNSAlias = "SERVER1".Add(retCat).DirectoryDNSAlias = "SERVER1". retcat.Item(i + 1). retCats.OnHold = true. for (int i = 0. i < retCats. retCats.Units = RetentionUnits.Name = "Finance". retcat. retcat.Period = 10. . retcat. retcat. IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass(). i++) { IRetentionCategory retCat = (IRetentionCategory)retcats.Description = "For finance depts". retcat. Return value S_OK Success.590 Retention API IRetentionCategory :: OnHold See “Holds object” on page 285. E_POINTER pVal is an invalid pointer.Count. retcat.IsVisible = true. retCats.Identifier = "xyz". retcat. [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass(). this lock feature can be controlled using the checkbox.Locked. Syntax HRESULT Locked([out. IRetentionCategory :: Locked This property enables a lock to be put on a retention category.Name. in the retention category properties.OnHold. [in] VARIANT_BOOL newVal New value. bool locked = retCat. HRESULT Locked([in] VARIANT_BOOL newVal).Description. Return value S_OK Success.Units. Parameters [out.Identifier. The property is read/write. This prevents an administrator from inadvertently modifying the retention category. string descr = retCat. Lock this Retention Category. retval] VARIANT_BOOL* pVal). long period = retCat.Retention API IRetentionCategory :: Locked string name = retCat. 591 . bool onHold = retCat. E_POINTER pVal is an invalid pointer.Period. bool isVis = retCat.IsVisible. RetentionUnits ru = retCat. retval] VARIANT_BOOL* pVal Pointer to current value. string ident = retCat. Remarks In the Administration Console. IsVisible. retCats. IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass(). retCats.Description = "For finance depts".Add(retCat).Item(i + 1).OnHold. long period = retCat.Period = 10. string descr = retCat.Name = "Finance".Months. retcat.IsVisible = true. i < retCats. retcat.Units.Count. retcat.Locked = true. retcat. i++) { IRetentionCategory retCat = (IRetentionCategory)retcats. . retCats. RetentionUnits ru = retCat. string ident = retCat. retcat. bool onHold = retCat. for (int i = 0.Units = RetentionUnits. string name = retCat.Identifier.OnHold = true.592 Retention API IRetentionCategory :: Locked Example [in] IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass(). retcat. retcat. bool isVis = retCat.DirectoryDNSAlias = "SERVER1". [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass(). retcat.Name.Identifier = "xyz".Period.Description.DirectoryDNSAlias = "SERVER1". Return value S_OK Success. See “Retention Date Basis enumeration” on page 563. HRESULT ExpiryBasis([in] RetentionDateBasis newVal). it is not returned by the Lookup method. retval] RetentionDateBasis* pVal). Remarks To retrieve the value of this property use the Get method. IRetentionCategory2 :: ExpiryBasis This property indicates the date from which storage expiry is calculated. [in] RetentionDateBasis newVal RetentionDateBasis enumeration value. E_INVALIDARG newVal is outside the bounds of the permitted range.Locked. The property is read/write. E_POINTER pVal is an invalid pointer. Parameters [out.Retention API IRetentionCategory2 :: ExpiryBasis bool locked = retCat. retval] RetentionDateBasis* pVal Enumeration value for date used to calculate storage expiry. Example [in] IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass(). 593 . Syntax HRESULT ExpiryBasis([out. retcat2. bool onHold = retCat2. string descr = retCat2. retcat2.ExpiryBasis.Months. bool isVis = retCat2. i < retCats. retcat2.OnHold.Period = 10.Name = "Finance".Identifier = "xyz". string ident = retCat2. retcat2.594 Retention API IRetentionCategory2 :: ExpiryBasis retCats. retcat2.Item(i + 1). for (int i = 0.Locked = true.IsVisible = true.IsVisible. retCats. string name = retCat2. retcat2. retCats.ExpiryBasis = RetentionDataBasis.DirectoryDNSAlias = "SERVER1".DirectoryDNSAlias = "SERVER1".OnHold = true. i++) { IRetentionCategory2 retCat = (IRetentionCategory2)retcats. long period = retCat2.Description = "For finance depts".Description. retcat2.Add(retCat). RetentionUnits ru = retCat2. [out] IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass().Identifier.Name.Units.Period. retcat2.Units = RetentionUnits.Count. . ExpiryBasisArchiveDate. retcat2. bool locked = retCat2. RetentionDataBasis rdb = retCat2. IRetentionCategory2 retcat2 = (IRetentionCategory2) new RetentionCategoryClass().Locked. Indexed properties are added to the archive index and can be used in archive searches. . The appendix includes information about how Enterprise Vault processes sender and recipient details when archiving and retrieving messages. A detailed description of how Enterprise Vault processes message items is provided in an appendix to this guide. and copying or moving archived messages. Enterprise Vault populates properties with information in the item.Appendix A Enterprise Vault properties This appendix includes the following topics: ■ About Enterprise Vault properties ■ System properties ■ Defined custom properties ■ Defined custom FSA properties ■ Defined custom SharePoint properties ■ Defined properties for Compliance Accelerator About Enterprise Vault properties This section lists the properties that are defined by Enterprise Vault: ■ System properties ■ Defined custom properties ■ Defined custom FSA properties ■ Defined custom SharePoint properties ■ Defined custom properties for Compliance Accelerator. This data is then stored with the archived item. When processing an item. ■ Multi-valued properties can have multiple values for a single index entry. practically limited to 32-bit integer maximum. any properties that are to be returned in search results must be defined as retrievable. where XXXX is the uppercase form of the property name. IndexPropSUBJ is the constant for the defined property. ■ Retrievable properties are those that can be returned in search results. IndexPropXXXX. In the following tables: ■ Searchable properties are those that can be used in search queries.Multi. ■ Sortable properties are those that can be used to order search results. and IndexPropRCAT is the constant for the system property. Properties marked as Yes are optimized in the index for sorting and provide the quickest results. For example.Retriev. Note: If you are using the Search API from a language that cannot access the string constants that are defined in the type library. "subj".596 Enterprise Vault properties System properties See “About storing and retrieving message items” on page 627.Fast able able Valued Sortable Subject/Title subj String Yes Yes No No Message Priority prio String Yes Yes No No Notes Although indexed as a string. The data available in search results for each item is a subset of these properties. Table A-1 System properties Description Name Type Search. and the type library defines many more properties than are currently used. Not all properties are present on every item. System properties This section lists the system properties defined in Enterprise Vault. "rcat". All properties in this table have defined constants. for IndexPropSSID use "ssid". any string literals used instead must match exactly the values from the type library. usually a numeric value. For example. . Technically no limit. SubmissionId for a sent message) iden String Yes Yes No No Last Modified date of the item mdat Date Yes Yes No Yes Original identifier for coid this component of the item String Yes Yes No No Data type of the item dtyp String Yes Yes No No E.Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. (e. usually a numeric value. Message Security secu String Yes Yes No No Currently not populated with any value. MSG De-duplication fingerprint of item fpdd String Yes Yes No No Can be used to find an exact match of a message or a document.g.Retriev. Technically no limit. usually a numeric value. 597 . Message Sensitivity sens String Yes Yes No No Although indexed as a string.Fast able able Valued Sortable Notes Message Importance impo String Yes Although indexed as a string. DOC.g. Range 1 Jan 1970 to 1 Jan 2038 Wildcard searches on this property are not supported. XLS. Content fingerprint of fpcn item String Yes Yes No No Can be used to find a match on an attachment or document content. Yes No No Technically no limit.Multi. practically limited to 32-bit integer maximum. Message Originator orgn String Yes No No No Currently not populated with any value. Original identifier for the item. practically limited to 32-bit integer maximum. Multi.Fast able able Valued Sortable Notes Archived Date adat Date Yes Yes No Yes Range 1 Jan 1970 to 1 Jan 2038 Original location of the locn item String Yes Yes No No A sequence of folders. Wildcard searches on this property are not supported. Shortcut location shct String No Yes No No Not supported from Enterprise Vault 10. Max 72 chars. User who archived the user item. . The last or leaf folder of original location lolf String No Yes No No The last or leaf folder of current location cllf String No Yes No No Original location lofn folder names (ordered) String No Yes Yes No Current location folder clfn names (ordered) String No Yes Yes No The item's Saveset identifier String Yes Yes No No ssid See “Note 1” on page 609. then the max number of chars is 76 + 1 + 10 => 87 chars. as per Note 1. String No Yes No No Currently not populated.0.Retriev. However. Original retention category Id String Yes Yes No No Max 112 chars. Current location of the clcn item String No Yes No No A sequence of folders.598 Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. if you include any attachment num. rcat Wildcard searches on this property are not supported. Created.Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. See “Note 3” on page 610. If item indexed by Enterprise Vault 10. Content cont String Yes Yes No No Search API: If item indexed by Enterprise Vault 9 or earlier. Languages lang String Yes No No No Categories/Keywords keys String Yes Yes Yes No Integer Yes Yes No Yes The size of the item in size KB Currently not populated. Content Management API: HTML representation to a max of 5 MB. Original retention category name rcnm String No Yes No No Max 32 chars Current retention category name crcn String No Yes No No Max 32 chars Index Sequence Number snum Integer Yes Yes No Yes 64-bit integer VaultEntryId of index vlid containing the item String No Yes No No Max 112 chars. See “Note 2” on page 609.Multi. 32-bit integer 599 . only the first 120 significant characters can be retrieved. by default the first 128 significant characters are retrieved.0 or later.Retriev. sent/received date or archivedDate Date Yes Yes No Yes Range 1 Jan 1970 to 1 Jan 2038 Yes No No Wildcard searches on this property are not supported.Fast able able Valued Sortable Notes Current retention category Id crct String Yes Max 112 chars. but this value can be configured. .Fast able able Valued Sortable Notes The number of attachments natc Integer Yes Yes No Yes 32-bit integer Permission VaultIds pvid for the item. this property cannot be used in a query to limit hits on attachments or top level documents. IPM.Retriev. practically limited to 32-bit integer max. Expiry date for the item (based on crct) edat Date Yes Yes No No Range 1 Jan 1970 to 1 Jan 2038 Number of days to expiry for the item (based on crct) ndte Integer Yes Yes No No 32-bit integer Rank value of the item rank when sorted by relevance (0 to 10. (Known as Archive Folder VaultIds) String Yes Yes Yes No Max 112 chars.600 Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. Attachment Number Integer Yes No No Yes 32-bit integer anum Zero for top-level item. This is because each index document contains the parent item and all the attachments.000) Integer No Yes No No 32-bit integer The item's original MAPI Message Class (e. Technically no limit.Multi. In ItemGranularity schema.Note) msgc String Yes Yes No No Message Flag Status flag Integer No Yes No No 32-bit integer Reason for missing content comr String Yes Yes No No See “Note 4” on page 610.g. Attachments only. Currently not populated for other items. followed by 32 hexadecimal characters representing a 128-bit GUID.Enterprise Vault properties System properties Table A-1 System properties (continued) Name Type Search. Identity ivid of the volume containing the item Integer No Yes No No 32-bit integer. Currently not populated for other items. Index Volume. The tsiz size of the top-level item in KB Integer No Yes No No 32-bit integer Conversation tracking cnid ID String Description Not applicable to items indexed using ItemGranularity schema. Attachments only. Yes Yes No No For MAPI items.Fast able able Valued Sortable Notes Attachments only.Multi. Conversation tracking cntp topic String No Yes No No Currently only populated for MAPI items.Retriev. Conversation tracking cnhv index String No Yes No No For MAPI items. followed by 10 hexadecimal characters for each reply/forward. 12 hexadecimal characters representing a datetime. 601 . Wildcard searches on this property are not supported. The taut author of the top-level item String No Yes No No Not applicable to items indexed using ItemGranularity schema. a 32 hexadecimal character representing a 128-bit GUID. The tsub subject/title of the top-level item String No Yes No No Not applicable to items indexed using ItemGranularity schema. Message Envelope Recipient. Message Envelope BCC: Recipient jrbc String Yes No Yes No Only present for Exchange journal messages. jrcc. Message Envelope Other Recipient jren String Yes No Yes No Only present for Exchange journal messages. Retrievable using the Content Management API. or BCC recipient. The property values include both email addresses and display names (where present). See Notes for jrcp.602 Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. CC. Message Envelope CC: jrcc Recipient String Yes No Yes No Only present for Exchange journal messages.Retriev. See “IArchiveMetaData :: IndexData” on page 236. vsid Integer No Yes No No 32-bit integer. Identity of the volume set containing the item Message Envelope recipient and sender information See “Note 5” on page 611. . See Notes for jrcp. Message Envelope TO: jrto Recipient String Yes No Yes No Only present for Exchange journal messages. menv String No No No No Only present for Exchange journal messages. Union of jrto. See Notes for jrcp.Multi. jrbc & jren See Notes for jrcp.Fast able able Valued Sortable Notes Index Volume Set. Used when the recipient details are not explicitly identified as a TO. jrcp String Yes No Yes No Only present for Exchange journal messages. reot & jrcp recp String Yes No Yes No Message Recipient.Fast able able Valued Sortable Notes Message Envelope jrau Author Union of jrfm. Message Recipient.Multi.Enterprise Vault properties System properties Table A-1 System properties (continued) Name Type Search. See Notes for jrcp. See “IArchiveMetaData :: IndexData” on page 236. Message Sender and Recipient sere String No No No No See “Note 6” on page 612.Retriev. See Notes for jrcp. Yes No Yes No Only present for Exchange journal messages. Message Envelope PP: jrpp Recipient Per Procurationem (by delegation to): person on whose behalf document has been written or message has been sent String Message Envelope Other Author String jaen Yes No Yes No Only present for Exchange journal messages. Retrievable using the Content Management API. rbdn & rndn String Yes No Yes No 603 . Message Envelope FROM: Recipient String Description jrfm No Yes No See Notes for jrcp. Union of redn. Used when the author details are not explicitly identified as FROM or PP. jrpp & jaen String Yes Only present for Exchange journal messages. redn Display/friendly name. See Notes for jrcp. rcdn. resm. Yes No Yes No Only present for Exchange journal messages. reea. Union of rtdn. Email address. Union of RTSM & RTOT rtea String Yes No Yes No TO: Recipient. CC: Recipient. up to a maximum of 256 characters. The retrievable value is the first few RTDN (or RTSM) values. rcdn Display/friendly name String Yes No Yes No . TO: Recipient. Other email address. rbot & rnot reot String Yes No Yes No TO: Recipient reto String Yes Yes No No Notes Max 256 chars. rcea. SMTP email address rtsm String Yes No Yes No TO: Recipient.604 Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. Email address. Union of rtea. rtdn Display/friendly name String Yes No Yes No TO: Recipient. Union of rtot. The retrievable value is the first few RTDN (or RTSM) values.Retriev. rcot. Union of rtsm. up to a maximum of 256 characters.Multi. rbsm & rnsm resm String Yes No Yes No Message Recipient. rbea & rnea reea String Yes No Yes No Message Recipient. SMTP email address. Other email address rtot String Yes No Yes No CC: Recipient recc String Yes Yes No No Max 256 chars.Fast able able Valued Sortable Message Recipient. rcsm. Email rcea address. Email address.Multi. Other email address rbot String Yes No Yes No Other Envelope Recipient renv String No Yes No No Max 256 chars.Fast able able Valued Sortable CC: Recipient. rbdn Display/friendly name String Yes No Yes No BCC: Recipient. Email rbea address. Other Envelope rndn Recipient. BCC: Recipient. Display/friendly name String Yes No Yes No Other Envelope rnea Recipient. The retrievable value is the first few RTDN (or RTSM) values. Union of rbsm & rbot String Yes No Yes No BCC: Recipient. up to a maximum of 256 characters.Retriev. Union of rcsm & rcot String Yes No Yes No CC: Recipient. up to a maximum of 256 characters. SMTP email address rcsm String Yes No Yes No CC: Recipient. Other email address rcot String Yes No Yes No BCC: Recipient rbcc String Yes Yes No No Description Notes Max 256 chars. Union of rnsm & rnot String Yes No Yes No 605 .Enterprise Vault properties System properties Table A-1 System properties (continued) Name Type Search. The retrievable value is the first few RTDN (or RTSM) values. SMTP rbsm email address String Yes No Yes No BCC: Recipient. ppgn & jrau String Yes Yes Yes No Author. auot.606 Enterprise Vault properties System properties Table A-1 System properties (continued) Name Type Search. audn Display/friendly name. auea Union of ausm. ppdn String Yes No Yes No Author. Union of audn. Union of wrsm. SMTP email address. auth auea. Other email auot address. ppot Notes . frot. ausm. Other email address String Yes No Yes No Number of Recipients nrcp Integer Yes Yes No Yes 32-bit integer Number of TO: Recipients nrto Integer No Yes No No 32-bit integer Number of CC: Recipients nrcc Integer No Yes No No 32-bit integer Number of BCC: Recipients nrbc Integer No Yes No No 32-bit integer Number of Other Envelope Recipients nren Integer No Yes No No 32-bit integer Author. writ. auot and wrea String Yes No Yes No Author. Email address. SMTP email address String Yes No Yes No Other Envelope rnot Recipient. frdn.Multi. from.Retriev.Fast able able Valued Sortable Other Envelope rnsm Recipient. Union of wrdn. Union of wrot. frsm ppsm String Yes No Yes No String Yes No Yes No Description ausm Author. frea. Email address. frsm. ppgn ppea.Fast able able Valued Sortable Notes Writer. Writer. ppsm & ppot.Enterprise Vault properties System properties Table A-1 System properties (continued) Name Type Search. frot from String Yes No Yes No FROM: frdn Display/friendly name String Yes No Yes No FROM: Email address. Writer. FROM: Union of frdn. Writer. Writer.Multi. SMTP email address wrsm String Yes No Yes No Currently not populated with any value. Per Procurationem (by delegation to) person on whose behalf document has been written or message has been sent String Yes No Yes No PP Display/friendly name String Yes Yes Yes No Description ppdn 607 . wrot String Yes No Yes No Currently not populated with any value. wrdn Display/friendly name String Yes No Yes No Currently not populated with any value. Union of wrdn.Retriev. frea Union of frsm & frot String Yes No Yes No FROM: SMTP e-mail address frsm String Yes No Yes No FROM: Other email address frot String Yes No Yes No PP Union of ppdn. wrea Union of wrsm & wrot String Yes No Yes No Currently not populated with any value. Other email address wrot String Yes No Yes No Currently not populated with any value. wrsm. writ wrea. g. Union of resm & ausm String Yes No Yes No Name Other email naot address. Union of redn & audn String Yes No Yes No Name Exchange email naea address. cend Calendar meeting end date Date No Yes No No Range 1 Jan 1970 to 1 Jan 2038 Event location E. Union of reea & auea String Yes No Yes No Name SMTP email nasm address. csrt Calendar meeting start date Date No Yes No No Range 1 Jan 1970 to 1 Jan 2038 Event end date E.608 Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. Union of ppsm. auth name String Yes No Yes No Name Display/friendly nadn name.Fast able able Valued Sortable PP Exchange email address.g. Calendar meeting location String No Yes No No text clon Notes . ppot ppea String Yes No Yes No PP SMTP email address ppsm String Yes No Yes No PP Other email address ppot String Yes No Yes No Name Union of recp. Union of reot & auot String Yes No Yes No Text Union of cont & subj String Yes No Yes No Event start date E.g.Retriev.Multi. for the first attachment: 849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B0. 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) .Retriev.Fast able able Valued Sortable Notes Task due date tddt Date No Yes No No Range 1 Jan 1970 to 1 Jan 2038 Task completed date tcdt Date No Yes No No Range 1 Jan 1970 to 1 Jan 2038 Task status tsts Integer No Yes No No Property value can be one of the following: 609 0 = Not started 1 = In progress 2 = Completed 3 = Paused 4 = Deferred Note 1 The ssid value returned for attachments is a concatenation of the SavesetId and the attachment number (see anum). the SavesetId must be extracted by removing the trailing full stop and attachment number: 849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B0 Note 2 For a message. For example. separated by a full stop.1 To use the Content Management API to retrieve the item.Multi.Enterprise Vault properties System properties Table A-1 System properties (continued) Description Name Type Search. Note 3 In the Search API.610 Enterprise Vault properties System properties Creation Time (PR_CREATION_TIME) Deferred Delivery Time (PR_DEFERRED_DELIVERY_TIME) For an attachment to a message or a document. then the current time (archival time) is used. In the extreme case that none of the above properties are available. the value is the HTML representation of the content to a maximum of 5 MB. In the Content Management API. HKEY_LOCAL_MACHINE \Software \Wow6432Node \KVS \Enterprise Vault \MaxIndexDataHTMLContentKB Note 4 Predefined values for comr property: enum EValueMissingReason { vmrNOREASON =0 No reason available vmrVALUENOTFOUND =1 Content does not exist vmrVALUENOTOBTAINED =2 Content could not be obtained vmrVALUECORRUPT =3 Content is (or appears to be) corrupt vmrNOCONVERTER =4 Not possible to convert content to suitable format (i. The 5 MB limit can be changed using the registry value. converter error) vmrCONVERSIONTIMEDOUT =6 Conversion of content timed out . only the first 120 characters of the textual representation of the content can be retrieved.e. no converter for this specific conversion) vmrCONVERSIONFAILED =5 Conversion of content failed (i.e. If the item index is 64-bit. but a content missing reason property (comr) with value vmrVALUENOTOBTAINED is returned instead. if the item index is 32-bit. If the size is larger than 5 MB. by default the first 128 characters of the textual representation of the content are retrieved. no value is returned. this is the created date of the object (PR_CREATION_TIME). but this value can be configured. User@email. GB18030) Note 5 The menv property contains the Message Envelope recipient and sender information for journal messages.Users@ourcompany. The following is an example of what it can contain: <?xml version="1.com</EA> </RC> </DL> </TO> <CC /> <BCC> 611 .com</EA> <RC> <DN>Administrator</DN> <EA>[email protected]</EA> </RC> <RC> <DN>CEO</DN> <EA>[email protected] Vault properties System properties vmrFORMATEXCLUDED =7 Content requires conversion but its data format is excluded from conversion vmrCONVERSIONBYPASS =8 Content requires conversion but conversion bypass has been set vmrVALUEENCRYPTED =9 Content is encrypted vmrCONVERTERUNINIT =10 Content requires conversion but converters are not available. in XML format.0" encoding="utf-16?"> <MSGENV> <RECP P1="true"> <TO> <RC> <DN>Joe User</DN> <EA>Joe.com</EA> </RC> <DL> <DN>Internal Users</DN> <EA>Internal.g. 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. Where a message has been sent on behalf of another user.User@email. The values returned for recipient properties (e.612 Enterprise Vault properties System properties <RC> <DN>Jill User</DN> <EA>Jill. the AUTH information will include both the sender (FROM) and delegate (PP) details.com</EA> </FROM> <PP><DN>Bill Stephens</DN><EA>BStephens@ourcompany. The following is an example of what it can contain: <?xml version="1.com</EA> </RC> </ENV> </RECP> <AUTH> <FROM><DN>Chris Davies</DN> <EA>CDavies@ourcompany. reto.0" encoding="utf-16?"> <MSG> <RECP> <TO> <RC> <DN>Joe User</DN> <EA>Joe. The AUTH element contains the message sender/author details (FROM). Note 6 The sere property contains the sender and recipient information in XML [email protected] </EA></PP> </AUTH> </MSGENV> This example is not exhaustive.User@email. 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.g.com</EA> </RC> <DL> . The full XSD also specifies DLs and their nesting.com</EA> </RC> </BCC> <ENV> <RC> <DN>John User</DN> <EA>John. 0 SP3. Enterprise Vault 7. ■ Missing content reasons returned in the missing content property. except that the root node is <MSG> rather than <MSGENV>.com</EA> </RC> </DL> </TO> <CC /> <BCC /> </RECP> <AUTH> <FROM><DN>Chris Davies</DN> <EA>CDavies@ourcompany. See “Enterprise Vault 2007 SP1. Enterprise Vault 7. and Enterprise Vault 6.0 SP3.com</EA> <RC> <DN>Administrator</DN> <EA>admin@ourcompany. 613 .0 SP3 and Enterprise Vault 2007 SP1. Enterprise Vault 7. comr. See “Enterprise Vault 2007 SP1.0 SP5.Enterprise Vault properties System properties <DN>Internal Users</DN> <EA>Internal.0 SP3 and Enterprise Vault 2007 SP1.0 SP5” on page 40.com</EA> </PP> </AUTH> </MSG> This example is not exhaustive. are available in Enterprise Vault 7.0 SP5” on page 40.0 [email protected]</EA> </RC> <RC> <DN>CEO</DN> <EA>[email protected] SP3. ■ <AUTH> element of the menv property is available in Enterprise Vault 6. and Enterprise Vault 6. Enterprise Vault 7.0 SP5” on page 40. Enterprise Vault 7.com</EA> </FROM> <PP><DN>Bill Stephens</DN> <EA>BStephens@ourcompany. See “Enterprise Vault 2007 SP1. and Enterprise Vault 6. Version information ■ The sere property is available in Enterprise Vault 6.0 SP3 and Enterprise Vault 2007 SP1. The sere property follows the same schema as the menv property. 0. Any non-supported character will be replaced with an underscore. csrt. Defined custom properties The following list of custom properties are also defined in Enterprise Vault. _ Names should not start with a number. cend. tcdt and tsts are available in Enterprise Vault 8. provides the following details: ■ Time the item was copied ■ The source item archive ■ Saveset ID If message is a journal message. Table A-2 Description Name Defined custom properties Type For an item copied by Move Vault. If an archive has been moved several times. the type of journal message Vault. Custom property sets and names can only contain the following characters: A-Z 0-1 .Notes able able Yes Yes See “Note 1” on page 615. tddt. ■ The shct property is not supported from Enterprise Vault 10.JournalType String Search. Yes Yes Currently defined values: ■ E2007 ■ E2003 ■ E2007ClearText E2007RMS See “Note 2” on page 615. there will be a value for each move. Properties containing GUIDs and hashes (up to 256 characters) will be indexed as literal and non-wildcarded. clon. .CopiedFrom String Archive.614 Enterprise Vault properties Defined custom properties ■ The event and task properties. in order to optimize memory utilization.Retriev.0 SP3 and later. Currently defined values: ■ 0 .external-out (one or more recipients are external) ■ Type of the message.vendor ■ FAX. The advanced setting in the Enterprise Vault Exchange Journaling policy.<source_item_Saveset_ID> For example.internal (all recipients are internal) ■ 2 . 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.200811140000000~200811141011170000~Z~ B082EF701FF8FB47509D5228C99D2B51 Note 2 If the message is from Exchange Server 2010 with journal report decryption enabled. 2009-11-17 13:37:012.MsgType String Yes Yes Currently defined values: ■ EXCH ■ SMTP ■ Bloomberg ■ IM. Vault.<source_archive_ID>.Enterprise Vault properties Defined custom properties Table A-2 Defined custom properties (continued) Description Name Type Message direction Vault. then 615 .Notes able able Yes Yes 32-bit integer as a string.external-in (sender is internal) ■ 3 . ClearText copies of RMS Protected items. If the value of Vault.JournalType is "E2007RMS".16B3597E77206FB4690FB46573DA6D7081110000 EVServer.vendor ■ DXL Note 1 Format is <UTC_datetime_of_copy>.undefined 1 . determines whether Enterprise Vault uses the clear text copy or the RMS-protected copy as the primary message during archiving.MsgDirection String Search. Both copies are stored in the saveset.domain.local.Retriev. CreatedBy String Yes Yes . Defined custom FSA properties The following list of custom properties are defined in Enterprise Vault for FSA items. Table A-4 Defined custom SharePoint properties Description Name Type Searchable Retrievable Notes Document title EVSP.DocId String Yes Yes Document version EVSP. 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.OriginalFileName String point of archival Yes Yes Indicator that item was imported from DLM Yes Yes EVFSADLMImport.Version String No Yes Check in comment EVSP.Comment String No Yes Display name of document editor EVSP. Table A-3 Description Defined custom FSA properties Name Type Searchable Retrievable Notes Original Name of file at the EVFSA.616 Enterprise Vault properties Defined custom FSA properties the primary message is the RMS-protected copy.Editor String Yes Yes Domain name (Windows account name) of document author EVSP.DLM String Currently only populated with the string "Imported" Defined custom SharePoint properties The following list of custom properties are defined in Enterprise Vault for SharePoint items.Title String Yes Yes SharePoint documentId EVSP. any SharePoint property EVSPP.ModifiedBy String Yes Yes SharePoint Site Id EVSP.DeptAuthor Department Ids that the item's author is a member of String Yes Yes Yes CA Dept IDs The set of CA KVSCA.SiteUrl String Yes Yes Customer configurable properties .DeptRecips Department Ids that the item's recipients are members of String Yes Yes Yes CA Dept IDs KVSCA.Department String Yes Yes Yes CA Dept IDs The union of KVSCA.DeptRecips Name Defined custom properties for Journaling Connector 617 .Notes Valued The set of CA KVSCA.DeptAuthor and KVSCA.Enterprise Vault properties Defined properties for Compliance Accelerator Table A-4 Defined custom SharePoint properties (continued) Description Name Type Searchable Retrievable Notes Domain name (Windows account name) of document editor EVSP.SiteId String Yes Yes SharePoint Site name EVSP.Site String No Yes SharePoint Site Url EVSP.<Sharepoint property name> String Yes Yes 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 A-5 Description Type Searchable Retrievable Multi. String Yes Yes Yes Policy names Policies. which either demand or suggest capture. defined in evtag.618 Enterprise Vault properties Defined properties for Compliance Accelerator Table A-5 Description Name Defined custom properties for Journaling Connector (continued) Type Searchable Retrievable Multi.inclusion The policy action is Vault. ■ NOACTION ■ EXCLUDE ■ INCLUDE . the sum result of all the applied policies. which do not affect capture either way.category the policy management software. they only categorize emails. which either preclude capture or advocate non-capture. defined in evtag.exclusion the policy management software.PolicyAction the overall action that should be taken on an item. defined in the policy management software. String Yes Yes Yes Policy names Policies. String Yes Yes Yes Policy names String Yes Yes Yes Defined values are: evtag.Notes Valued Policies. Wait and retry later.Appendix B API return values This appendix includes the following topics: ■ About API return values ■ Content Management API return values ■ Retention API return values ■ Search API return values ■ External Filter API Event log messages About API return values This appendix lists the Enterprise Vault API return values. . Content Management API return values Table B-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. or is only able to read data due to ongoing backups. The server is busy. or has insufficient resources. or item. CONTENTMANAGEMENTAPI_E_NOT_SUPPORTED 0x8004030E The operation is not supported. 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 CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND 0x80040307 Item not found CONTENTMANAGEMENTAPI_E_NOT_FOUND 0x80040308 Archive.620 API return values Retention API return values Table B-1 Content Management API return values (continued) Return value Value Description CONTENTMANAGEMENTAPI_E_NO_ACCESS 0x80040303 Caller has insufficient permissions to access the vault store. Retention API return values The following return values are defined for the Retention API: . or archive is in a read-only state. 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. SiteIdNotFound 0x800704BA Returned if the site specified by DirectoryDNSAlias does not exist. and one already exists with the same name.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 621 . RetentionCategoryNotExist 0x80070002 Returned when attempting to update a retention category. and the RetentionCategoryId does not exist in the Enterprise Vault directory. Search API return values The following return values are defined for the Search API: Table B-3 Search API return values Return value Value Description rvS_OK 0x00000000 Successful completion rvS_FALSE 0x00000001 Sucessful .API return values Search API return values Table B-2 Retention API return values Return value Value Description RetentionCategoryAlreadyExists 0x800700b7 Returned when attempting to add a retention category. The maximum is defined by the MaxSearchResultsPerVolumeSet property. . rvINDEXING_E_INVALID_QUERY 0xC0041C53 The search was rejected since the search query was invalid.622 API return values Search API return values Table B-3 Search API return values (continued) Return value Value Description 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. rvINDEXING_E_TOO_MANY_VOLUMES 0xc0041C82 The search request was rejected because there are too many index volumes to search. 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 maximum is defined by the MaxSearchIndexVolumeSets property. The timeout is defined by the Timeout property. The agent will now shut down external filters fails to load.API return values External Filter API Event log messages Search API return values (continued) Table B-3 Return value Value Description rvINDEXING_E_ILLEGAL_WILDCARD_QUERY 0xC0041C5E The search was rejected since the search query contained invalid wildcard terms. or as it cannot reliably continue. No more filters will be processed. (The filter's ProcessFilter method returns a non-zero return value). External Filter API Event log messages The following events are written to the Enterprise Vault event log by the Task Filter Controller. Error: error information Mailbox: mailbox DN Message Folder: folder name Message Title: message title 623 . Table B-4 Exchange Task Filter Controller log messages Event Type Description Example 3144 Error Logged by the filter controller Failed whilst initializing the Filter if one or more of the registered Controller. Error: error information 3263 Error Logged by the filter controller when an external filter returns an error when processing a message. An error occurred processing the external filter ‘filter prog id’. rvINDEXING_E_INDEX_SEARCH_FAILED 0xC0041C0E The search failed due to a failure to search one or more of the targeted index volumes sets. 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. fails to initialize. Exchange Server filtering The following messages are written to the Enterprise Vault event log by the Exchange Task Filter Controller. The filter controller stops processing the message. 45330 Informational Logged by the filter controller External Filter ‘filter prog id’ stopped.. Table B-5 Domino Journaling task filter controller log messages Event Type Description Example 41086 Informational Logged by the filter controller The Domino external filter ‘filter_name’ at the point of initializing each has started. at the point of initializing each external filter.. errors are encountered. 45329 Informational Logged by the filter controller External Filter ‘filter prog id’ initializing. 41087 Informational Logged by the filter controller The Domino external filter ‘filter_name’ at the point of de-initializing has stopped. incorrect or the DLL has not been registered. Please check the ProgId or register the DLL for the external filter. This Task will now shut down. . 3147 Error Logged by the filter controller An error has occurred initializing the when an external filter returns external filter ‘filter prog id’. each installed filter. an error when initializing. (The Error: error information filter's Initialize method returns a non-zero return value). installed filter. at the point of stopping each external filter. 3150 Error Logged by the filter controller Whilst processing external filters too when a stream of consecutive many consecutive errors have occurred. Domino Server filtering The following messages are written to the Enterprise Vault event log by the Domino Journaling task filter controller. Either the ProgId is instance of an external filter.624 API return values External Filter API Event log messages Table B-4 Exchange Task Filter Controller log messages (continued) Event Type Description Example 3146 Error Logged by the filter controller Failed to initialize the external filter with when attempting to create an ProgId ‘filter prog id’. method FilteringComplete. The reason for the error is contained in the message text. 41339 Warning Logged by the filter controller Error in external filter method if it encounters an error in the FilteringComplete. 41295 Informational Logged by the filter controller The file system external filter ‘filter_name’ when the filter stops. count has reached the threshold. has stopped. a file. File System filtering The following messages are written to the Enterprise Vault event log by the File System Archiving task filter controller. 41036 Error Logged by the filter controller if a filter raises an error during initialization.. 625 .Reason: An applicable RuleSet has not been defined for database ‘Symantec\db_name.. The reason for the error is contained in the message text. File: FileUNCPath Error: error_message 41338 Error Logged by the filter controller The File System Archiving task has when the error count reaches stopped because th external filter error the threshold level. has started.API return values External Filter API Event log messages Table B-5 Domino Journaling task filter controller log messages (continued) Event Type Description Example 41088 Error Logged by the filter controller if a filter raises an error during processing. Unable to start the FilterController The following error occurred: Unable to initialize() filter ‘filter_name’.nsf’ and a default Content Category has not been specified. Table B-6 File System Archiving task filter controller log messages Event Type Description Example 41294 Informational Logged by the filter controller The file system external filter ‘filter_name’ when the filter starts. The Domino external filter ‘filter_name’ failed to process an item. Reason: . 41296 Warning Logged by the filter controller The file system external filter ‘filter_name’ when the filter fails to process failed to process a file. filter_name. if it encounters an error in the method Shutdown. 41362 Warning Logged by the File System The file system external filter filter_name Archiving task when it receives has requested to stop the File System a shutdown request from the Archiving task: archiving_task_name filter. filter filter_name. Error: error_message 41337 Warning Logged by the filter controller Failed to initialize the file system external if it fails to initialize the filter. it failed to load or initialize a file system external filter.626 API return values External Filter API Event log messages Table B-6 File System Archiving task filter controller log messages (continued) Event Type Description Example 41340 Warning Logged by the filter controller Error in external filter method Shutdown. 41336 Warning Logged by the filter controller Failed to load the file system external filter if it fails to load the filter. Error: error_message 41361 Error Logged by the File System The File System Archiving Task Archiving task when it fails to ‘archiving_task_name’ has stopped because load or initialize the filter. . In particular. and SMTP messages. rather than the more unwieldy Exchange X. improvements have been made to the way that address details in Exchange messages are resolved to users’ SMTP addresses. especially in the handling of sender and recipient details when indexing the archived items. The Content Management API processing of messages has been enhanced over several Enterprise Vault releases.500 Directory Name style address. Lotus Notes. This is important for Enterprise Vault Discovery Accelerator searches. which are typically based on users’ SMTP addresses. .Appendix C Understanding how Enterprise Vault archives and indexes messages This appendix includes the following topics: ■ About storing and retrieving message items ■ Exchange (MAPI) messages ■ Lotus Notes messages ■ SMTP messages ■ Copying message items ■ Why a retrieved item is not a binary copy of the original item About storing and retrieving message items Enterprise Vault recognizes and supports the insertion of Exchange (MAPI). Enterprise Vault now indexes SMTP addresses in preference to Exchange email addresses. As a result. See “IItem :: Get” on page 194.628 Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages The Enterprise Vault archiving agents for Exchange (MAPI). BCC recipients and alternate recipient delivery. The primary aim is to ensure that Enterprise Vault index searches on a user’s primary email address also find messages in which the user was addressed using a secondary or alternative email address. and are also used when indexing the archived item. and SMTP messages augment the sender and recipient details from the message with additional values sourced from the domain directory of mail users. Exchange (MAPI) messages This section describes how the Enterprise Vault Exchange archiving agents and Content Management API process sender and recipient information when archiving Exchange mailbox and journal messages. read . These details are stored as the Message Sender and Recipients (sere) property in the archived item. and includes information about key changes over recent releases of Enterprise Vault. Details of the properties that are defined in Enterprise Vault. This includes interpersonal messages. These properties are processed to generate another structured collection of enhanced sender and recipient details. The archiving agent processes the message sender and recipients to generate a structured collection of enhanced sender and recipient details. The sere property can be retrieved using the Content Management API. delivery reports. The menv property can also be retrieved using the Content Management API. How the Enterprise Vault archiving agent processes Exchange mailbox messages The Enterprise Vault Exchange archiving agent archives all mailbox messages in the same manner. The Enterprise Vault Exchange and Domino journal archiving agents also augment the sender and recipient details for a journal message with additional values sourced from both the message envelope and the domain directory of mail users. including Distribution List expansion. See “System properties” on page 596. The details are used when indexing the archived item. This appendix describes how Enterprise Vault processes different message types. The message envelope typically provides further details of the message routing. These details are stored as the Message Envelope Sender and Recipients (menv) property in the archived item. including the Message Sender and Recipients (sere) and Message Envelope Sender and Recipients (menv) properties. are included in this manual. Lotus Notes. sent representing. Otherwise the best values from the available message properties are used. and so on. with precedence given to an SMTP address value over an Exchange address value. the sere property is augmented with the display name and default SMTP addresses of the members of the Distribution List. tasks. The message is stored as the primary content of the archived item. The message sender and recipients are processed in conjunction with the Exchange Global Address List (GAL) to generate the Message Sender and Recipients (sere) property. In all cases. calendar items. if a current Exchange GAL entry is identified by the appropriate MAPI entry id property in the message. Furthermore if a recipient maps to a Distribution List entry in the Exchange GAL. Figure C-1 details the workflow for generating the sender element of the sere property from the message sender properties. and an email address. and the advanced setting Expand Distribution List in the Enterprise Vault Exchange archiving policy is enabled. The sender. then the display name and default SMTP address are used from that GAL entry. and each recipient listed in the message are recorded in the sere property with an entry containing a friendly name.Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages receipts. 629 . 630 Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages Figure C-1 Read message sender properties Does Exchange GAL entry exist for sender entry id? Exchange archiving agent workflow for generating the sender entry of the sere property MAPI properties Display name: PR_SENDER_NAME (ID:0x0C1A) Address Book Entry Id: PR_SENDER_ENTRYID (ID:0x0C19) Email address: PR_SENDER_EMAIL_ADDRESS (ID:0x0C1F) Email address type: PR_SENDER_ADDRTYPE (ID:0x0C1D) yes no Read Exchange GAL entry Does Exchange GAL entry contain default SMTP address? no Is sender email address an SMTP address? MAPI properties Alternate email addresses: PR_EMS_AB_PROXY_ADDRESSES (ID:0x800F) Default SMTP address: PR_SMTP_ADDRESS (ID:0x39FE) Add sender display name and GAL default SMTP address to Message Sender and Recipient property yes Add sender display name and sender email address to Message Sender and Recipient property yes no Is sender email address an Exchange address? yes Search Active Directory for user object containing Exchange address SMTP address found in Active Directory? no LDAP properties Legacy Exchange address: legacyExchangeDN Email-Addresses: mail yes Add sender display name and Active Directory SMTP address to Message Sender and Recipient property Add sender display name and sender email address to Message Sender and Recipient property . but the logic is based on the sent representing MAPI properties in the message: Display name: PR_SENT_REPRESENTING_NAME (ID:0x0042) Exchange Address Book Entry Id: PR_SENT_REPRESENTING _ENTRYID (ID:0x0041) Email address: PR_SENT_REPRESENTING _EMAIL_ADDRESS (ID:0x0065) Email address type: PR_SENT_REPRESENTING _ADDRTYPE (ID:0x0064) Figure C-2 details the workflow for generating each of the recipient elements of the sere property from the message recipient properties. 631 .Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages The same workflow is used to generate the sent representing element of the sere property. 632 Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages Exchange archiving agent workflow for generating the recipient entry of the sere property Figure C-2 MAPI properties Recipient Type: PR_RECIPIENT_TYPE (ID:0x0C15) Display name: PR_DISPLAY_NAME (ID:0x3001) Exchange Address Book Entry Id: PR_ENTRYID (ID:0x0FFF) Email address: PR_EMAIL_ADDRESS (ID:0x3003) Email address type: PR_ADDRTYPE (ID:0x3002) Default SMTP Address: PR_SMTP_ADDRESS (ID:0x39FE) Original email address: PR_OrgEmailAddr (ID:0x403E ) Original email address type: PR_OrgAddrType (ID:0x403D) Read message recipient properties Does Exchange GAL entry exist for recipient entry id? no MAPI properties Display Name: PR_DISPLAY_NAME (ID:0x3001) Alternate email addresses: PR_EMS_AB_PROXY_ADDRESSES (ID:0x800F) Default SMTP address: PR_SMTP_ADDRESS (ID:0x39FE) Read Exchange Global Address List entry yes Is entry a DL and is DL expansion archiving policy enabled? yes Expand DL members and add each members’ display name and default SMTP address to Message Sender and Recipient property no no Is recipient default SMTP address present? Add GAL display name and default SMTP address to Message Sender and Recipient property Does Exchange GAL entry contain default SMTP address? yes Add GAL or recipient display name and GAL default SMTP address to Message Sender and Recipient property yes Add GAL or recipient display name and recipient default SMTP address to Message Sender and Recipient property yes Add GAL or recipient display name and recipient email address to Message Sender and Recipient property yes Add GAL or recipient display name and recipient original email address to Message Sender and Recipient property no Add GAL or recipient display name and recipient email address to Message Sender and Recipient property no Is recipient email address an SMTP address? no Is recipient original email address an SMTP address? . and stored in the archived item.x a Enterprise Vault 10.msg). dependent on the version of Enterprise Vault.0.x Message Sender and No Recipients (sere) property is generated on insertion. Enterprise Vault 9. The message is stored as the primary content of the archived item. Table C-1 Content Management API support for the sere property for MAPI messages Enterprise Vault 8. and supports both Unicode and non-Unicode items.0 SP1 included a performance improvement and a fix for an issue introduced in Enterprise Vault 9.x Enterprise Vault 9. 633 . The issue prevented Enterprise Vault from indexing the sender/recipient details correctly for some items (Ref 901-5786). and stored in the archived item Yes Yes If the Message Sender and Recipients (sere) property is not present in the archived item. such that the sere property is generated on ingest.Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages How the Content Management API processes Exchange mailbox messages The Content Management API supports MAPI messages inserted in Outlook Message Format (. The message sender and recipients are processed to generate the Message Sender and Recipients (sere) property at various points in the handling of the archived item. Later versions of Enterprise Vault aim to replicate the behavior of the Enterprise Vault Exchange archiving agent. it is generated dynamically when the item is indexed Yes Yes Yes Yes Yes Sender/Recipient No details are generated dynamically when the item is retrieved (if not stored in archived item) a. From Enterprise Vault 9.0 Exchange address resolution uses Active Directory.0. . There is no expansion of distribution lists. the Exchange GAL is used. regardless of the advanced setting Expand Distribution Lists in the Exchange archiving policy. Figure C-3 details the workflow for generating the sender element of the sere property from the message sender properties. In releases prior to Enterprise Vault 9.634 Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages The Content Management API uses the display name and SMTP email address values from the message in preference to attempting Exchange address resolution. Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages Content Management API workflow for generating sender entry of sere property Figure C-3 Read message sender properties MAPI properties Display name: PR_SENDER_NAME (ID:0x0C1A) Exchange Address Book Entry Id: PR_SENDER_ENTRYID (ID:0x0C19) Email address: PR_SENDER_EMAIL_ADDRESS (ID:0x0C1F) Email address type: PR_SENDER_ADDRTYPE (ID:0x0C1D) Is sender email address an SMTP address? Add sender display name and sender email address to Message Sender and Recipient property yes no Is Enterprise Vault release 9.0 or later? yes Search Active Directory for user object containing sender email address SMTP address found in Active Directory? LDAP properties Legacy Exchange address: legacyExchangeDN Email-Addresses: mail yes Add sender display name and Active Directory SMTP address to Message Sender and Recipient property no no Does Exchange GAL entry exist for sender entry id? no yes Read Exchange GAL entry Does Exchange GAL entry contain default SMTP address? no Add sender display name and sender email address to Message Sender and Recipient property MAPI properties Alternate email addresses: PR_EMS_AB_PROXY_ADDRESSES (ID:0x800F) Default SMTP address: PR_SMTP_ADDRESS (ID:0x39FE) yes Add sender display name and GAL default SMTP address to Message Sender and Recipient property Add sender display name and sender email address to Message Sender and Recipient property 635 . but the logic is based on the message sent representing MAPI properties: Display name: PR_SENT_REPRESENTING_NAME (ID:0x0042) Exchange Address Book Entry Id: PR_SENT_REPRESENTING _ENTRYID (ID:0x0041) Email address: PR_SENT_REPRESENTING _EMAIL_ADDRESS (ID:0x0065) Email address type: PR_SENT_REPRESENTING _ADDRTYPE (ID:0x0064) Figure C-4 and Figure C-5 detail the workflow for generating each of the recipient elements of the sere property from the message recipient properties.636 Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages The same workflow is used to generate the sent representing element of the sere property. . Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages Figure C-4 Read message recipient properties Is recipient default SMTP address present? Content Management API workflow for generating the recipient entry of the sere property MAPI properties Recipient Type: PR_RECIPIENT_TYPE (ID:0x0C15) Display name: PR_DISPLAY_NAME (ID:0x3001) Exchange Address Book Entry Id: PR_ENTRYID (ID:0x0FFF) Email address: PR_EMAIL_ADDRESS (ID:0x3003) Email address type: PR_ADDRTYPE (ID:0x3002) Default SMTP Address: PR_SMTP_ADDRESS (ID:0x39FE) Original email address: PR_OrgEmailAddr (ID:0x403E ) Original email address type: PR_OrgAddrType (ID:0x403D) yes Add recipient display name and recipient default SMTP address to Message Sender and Recipient property yes Add recipient display name and recipient email address to Message Sender and Recipient property yes Add recipient display name and recipient original email address to Message Sender and Recipient property no Is recipient email address an SMTP address? no Is recipient original email address an SMTP address? no 637 . 0 the Message Sender and Recipients property may not be available when retrieving MAPI messages using the Content Management API. prior to Enterprise Vault 9.0 or later? yes SMTP address found in Active Directory? no no yes Read Exchange Global Address List entry Add recipient display name and recipient email address to Message Sender and Recipient property MAPI properties Alternate email addresses: PR_EMS_AB_PROXY_ADDRESSES (ID:0x800F) Default SMTP address: PR_SMTP_ADDRESS (ID:0x39FE) Does Exchange GAL entry contain default SMTP address? no no Add recipient display name and Active Directory SMTP address to Message Sender and Recipient property yes no Does Exchange GAL entry exist for recipient entry id? LDAP properties Legacy Exchange address: legacyExchangeDN Email-Addresses: mail Search Active Directory for user object containing recipient email address yes Add recipient display name and GAL default SMTP address to Message Sender and Recipient property Add recipient display name and recipient email address to Message Sender and Recipient property As indicated in Table C-1. This is particularly relevant to items that were originally inserted using the Content Management API.638 Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages Content Management API workflow for generating the recipient entry of the sere property (continued) Figure C-5 no Is Enterprise Vault release 9. In such cases the basic sender and recipient properties are available: . Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages FROM: Display/friendly name (frdn) FROM: SMTP address (frsm) FROM: Other email address (frot) PP: Display/friendly name (ppdn) PP: SMTP address (ppsm) PP: Other email address (ppot) TO: Recipient display/friendly name (rtdn) TO: Recipient SMTP address (rtsm) TO: Recipient Other email address (rtot) CC: Recipient display/friendly name (rcdn) CC: Recipient SMTP address (rcsm) CC: Recipient other email address (rcot) BCC: Recipient display/friendly name (rbdn) BCC: Recipient SMTP address (rbsm) BCC: Recipient Other email address (rbot) The property values are completed with the message sender and recipient email address values. in accordance with the email address type from the following MAPI properties: Sender display name: PR_SENDER_NAME (ID:0x0C1A) Sender email address type: PR_SENDER_ADDRTYPE (ID:0x0C1D) Sender email address: PR_SENDER_EMAIL_ADDRESS (ID:0x0C1F) Sent representing display name: PR_SENT_REPRESENTING_NAME (ID:0x0042) Sent representing email address type: PR_SENT_REPRESENTING _ADDRTYPE (ID:0x0064) Sent representing email address: PR_SENT_REPRESENTING _EMAIL_ADDRESS (ID:0x0065) Recipient type: PR_RECIPIENT_TYPE (ID:0x0C15) Recipient display name: PR_DISPLAY_NAME (ID:0x3001) Recipient email address type: PR_ADDRTYPE (ID:0x3002) Recipient email address: PR_EMAIL_ADDRESS (ID:0x3003) 639 . formatted text that reports recipient routing actions. When the Enterprise Vault Exchange archiving agent archives envelope journal messages. The envelope journal message is stored as the primary content of the archived item. with the exception of the envelope journal report messages that are delivered to an Exchange journal mailbox. and the envelope journal reports are stored separately within the archived item. recipient redirections and distribution list expansions. The envelope journal message contains the original message as an attachment. and archives them all in a single archived item. the journal reports and the textual content of the envelope message body are parsed to build the Message Envelope Sender and Recipients (menv) property. The primary content of the archived item is returned when the Content Management API is used to retrieve the archived item. How the Enterprise Vault archiving agent processes Exchange envelope journal messages The Enterprise Vault Exchange archiving agent handles all MAPI messages exactly the same. The envelope journal message body is a journal report. The original message sender and recipient details are processed as described for Exchange mailbox messages. it attempts to collate all journal reports for a given original message. . The envelope journal report is not parsed. Note also that you cannot correlate display names and corresponding email address values using these properties. In addition. BCC recipient information is only available for messages that are archived from the mailbox Sent Items folder. and includes BCC recipients.640 Understanding how Enterprise Vault archives and indexes messages Exchange (MAPI) messages Typically the SMTP address properties are only populated for non-Exchange senders and recipients. The envelope journal reports are not currently accessible using the Content Management API. See “How the Enterprise Vault archiving agent processes Exchange mailbox messages” on page 628. an envelope journal message is archived as a MAPI message. there is no special processing for envelope journal messages that are stored using the Content Management API. and hence the Message Envelope Sender and Recipient (menv) property is neither indexed nor is it available when the archived item is retrieved using the Content Management API. The original message is stored as the primary content of the archived item. How the Content Management API processes Exchange envelope journal messages Unlike the Enterprise Vault Exchange archiving agent. if not already present. the user’s primary SMTP and Notes email addresses are added to the sere property. The message sender and recipients are processed in conjunction with the Domino Directory to generate the Message Sender and Recipients (sere) property. the canonical. When the 641 . The email address from the message is always used. the Domino Directory is used to look up the email address.dvns) format. In this case.Understanding how Enterprise Vault archives and indexes messages Lotus Notes messages Lotus Notes messages This section describes how the Enterprise Vault Domino archiving agents and the Content Management API process sender and recipient information for Lotus Notes mailbox and journal messages. Additionally the sere property is augmented if the advanced setting Expand distribution lists is enabled in the Domino archiving policy. The resulting Enterprise Vault Note Stream file is inserted using the Content Management API. as resolved from the Domino Directory: ■ Display name ■ Primary SMTP address ■ Primary Notes address When Lotus Notes names are processed.0 the Content Management API supports Notes messages inserted in Enterprise Vault Note Stream (. If the advanced setting Lookup email addresses is enabled in the Domino archiving policy. and each recipient listed in the message are recorded in the sere property. the canonical name “CN=John Smith/OU=Sales/O=Acme” results in a display name and an email address of “John Smith/Sales/Acme”. Lotus Notes messages have to be extracted from an NSF database into an Enterprise Vault Note Stream file using the Enterprise Vault NSF Manager API. For example. and a recipient address is listed in the Domino Directory as a distribution list. How the Enterprise Vault archiving agent processes Lotus Notes mailbox messages The Enterprise Vault Domino archiving agent archives all Lotus Notes messages in the same manner. and the same value is used as the email address. hierarchical form names are translated to their abbreviated format. From the Domino Directory. the sere property is augmented with the following information for the members of the distribution list. The abbreviated hierarchical name format is used as the display name. See “NSF Manager API” on page 330. Since Lotus Notes messages have no native standalone file format. From Enterprise Vault 8. The sender. together with an entry containing a friendly name and one or more email addresses. sent representing. The message is stored as the primary content of the archived item. For example. the address “JSmith@acme. Figure C-6 details the workflow for generating the sender element of the sere property from the message sender properties. For SMTP addresses without a display name element. For example.642 Understanding how Enterprise Vault archives and indexes messages Lotus Notes messages Lotus Notes name is sourced from the Domino Directory.com” results in a display name of “JSmith” and an email address “JSmith@acme. the local part of the address is used as the display name. primary SMTP address and sender email address to Message Sender and Recipient property no Add sender display name and sender email address to Message Sender and Recipient property .com”. the canonical name “CN=John Smith/OU=Sales/O=Acme” in the mail domain “ACMEInc” results in the display name and email address values of “John Smith/Sales/Acme@ACMEInc”. Domino archiving agent workflow for generating the sender entry of the sere property Figure C-6 Notes fields Read message sender Email address: From properties Domain name: FromDomain Is archiving policy Lookup email addresses enabled? yes Search Domino Directory for user or group in sender domain containing sender email address Domino Directory fields Users view: $Users Person mail domain name: MailDomain Person full name: Fullname Person SMTP address: InternetAddress Group name: ListName Group type: GroupType Group SMTP address: InternetAddress Group members: Members no User or group entry found? yes Add Domino Directory entry display name. the abbreviated hierarchical name is appended with the entry’s mail domain name. primary Notes address. 643 . but the logic is based on the message sent representing field. Figure C-7 details the workflow for generating each of the recipient elements of the sere property from the message recipient properties. the Principal field.Understanding how Enterprise Vault archives and indexes messages Lotus Notes messages The same workflow is used for generating the sent representing element of the sere property. that is. primary SMTP address and sender email address to Message Sender and Recipient property no Add sender display name and sender email address to Message Sender and Recipient property . primary SMTP address and sender email address to Message Sender and Recipient property Expand DL members and add each member’s display name and primary Notes and SMTP email addresses to Message Sender and Recipient property yes Add Domino Directory entry display name. primary Notes address.644 Understanding how Enterprise Vault archives and indexes messages Lotus Notes messages Domino archiving agent workflow for generating the recipient entry of the sere property Figure C-7 Read message recipient properties and process each recipient Is archiving policy Lookup email addresses enabled? no Notes fields TO recipients: SendTo CC recipients: CopyTo BCC recipients: BlindCopyTo yes Domino Directory fields Users view: $Users Person mail domain name: MailDomain Person full name: Fullname Person SMTP address: InternetAddress Group name: ListName Group type: GroupType Group SMTP address: InternetAddress Group members: Members Search Domino Directory for user or group in sender domain containing sender email address Group entry found and DL expansion archiving policy enabled? yes no User or group entry found? Add Domino Directory entry display name. primary Notes address. Figure C-8 Content Management API workflow for generating the sender entry of the sere property Read message sender properties Notes field Email address: From Add sender display name and sender email address to Message Sender and Recipient property The same workflow is used for generating the sent representing element of the sere property. together with an entry containing a display name. and each recipient listed in the message are recorded in the sere property. and the email address as listed in the message. but the logic is based on the message sent representing field. are the same as used by the Domino archiving agent. 645 . The values parsed from the addresses. the Principal field. Figure C-8 details the workflow for generating the sender element of the sere property from the message sender properties.Understanding how Enterprise Vault archives and indexes messages Lotus Notes messages How the Content Management API processes Lotus Notes mailbox messages The message is stored as the primary content of the archived item. The sender. Figure C-9 details the workflow for generating each of the recipient elements of the sere property from the message recipient properties. The message sender and recipients are processed to generate the Message Sender and Recipients (sere) property. and used for the display name and email address. which is stored in the archived item. that is. sent representing. The Domino Directory is not used to lookup additional information. the journal message is stored as the primary content of the archived item. The journal message contains additional Notes fields detailing the journal recipients. The sender. including distribution list expansions. the user’s primary SMTP and Notes email addresses are added to the menv property. together with an entry containing a friendly name and one or more email addresses. From the Domino Directory. The display name and email address from the Notes field are always used. The Domino Directory is used to look up the email address. with the exception of journal messages that are delivered to a Domino journaling database. and each recipient listed in the message are recorded in the Message Sender and Recipients (sere) property as described for Lotus Notes mailbox messages. Figure C-10 details the workflow for generating each of the recipient elements of the menv property from the message journal recipient properties.646 Understanding how Enterprise Vault archives and indexes messages Lotus Notes messages Figure C-9 Content Management API workflow for generating the recipient entry of sere property Read message recipient properties and process each recipient Notes fields TO recipients: SendTo CC recipients: CopyTo BCC recipients: BlindCopyTo Add sender display name and sender email address to Message Sender and Recipient property How the Enterprise Vault archiving agent processes Lotus Notes journal messages The Enterprise Vault Domino archiving agent handles all Lotus Notes messages exactly the same. When the Enterprise Vault Domino archiving agent archives journal messages. if not already present. Additionally the journal recipients Notes fields are processed to generate the Message Envelope Sender and Recipients (menv) property. . See “How the Enterprise Vault archiving agent processes Lotus Notes mailbox messages” on page 641. sent representing. This means that the Message Envelope Sender and Recipient (menv) property is neither 647 . primary Notes address. The journal recipient Notes fields are not processed. primary SMTP address and sender email address to Message Envelope Sender and Recipient property Add sender display name and sender email address to Message Envelope Sender and Recipient property How the Content Management API processes Lotus Notes journal messages Unlike the Enterprise Vault Domino archiving agent.Understanding how Enterprise Vault archives and indexes messages Lotus Notes messages Figure C-10 Read message envelope recipient properties and process each recipient Search Domino Directory for user or group containing sender email address User or group entry found? Notes fields Journal recipients: $JournalRecipients Journal expanded group recipients: $JournalRecipientsExpanded_<n> or Envelope recipients: Recipients Domino Directory fields Users view: $Users Person mail domain name: MailDomain Person full name: Fullname Person SMTP address: InternetAddress Group name: ListName Group type: GroupType Group SMTP address: InternetAddress Group members: Members yes no Domino archiving agent workflow for generating recipient entry of menv property Add Domino Directory entry display name. there is no special processing for journal messages. 0. Table C-2 Content Management API support for the sere property for SMTP messages Enterprise Vault 8. See Table C-2 on page 648. SMTP messages The Content Management API supports SMTP messages inserted in MIME format (.eml). nor is it available when the archived item is retrieved using the Content Management API. The message sender and recipients are processed to generate sere property at various points in the handling of an archived item. The message is stored as the primary content of the archived item. There is no difference in behavior between SMTP messages archived using the Content Management API and those archived by the Enterprise Vault SMTP Archiving feature.x Enterprise Vault 10. dependent on the version of Enterprise Vault.x No Yes . Since the generation of the sere property does not add any additional information to that available in the message.648 Understanding how Enterprise Vault archives and indexes messages SMTP messages indexed. there is no difference in search capabilities for SMTP messages that are indexed prior to Enterprise Vault 10.x Message Sender and No Recipients (sere) property is generated on insertion and stored in the archived item Enterprise Vault 9. How the Content Management API processes SMTP messages This section describes how the Content Management API processes sender and recipient information when archiving SMTP messages. x Enterprise Vault 10.Understanding how Enterprise Vault archives and indexes messages SMTP messages Table C-2 Content Management API support for the sere property for SMTP messages (continued) Enterprise Vault 8. the sere property may not be available when retrieving SMTP messages using the Content Management API.x No No Yes Sender/Recipient No details are generated dynamically when the item is retrieved (if not stored in archived item) No Yes If the Message Sender and Recipients (sere) property is not present in the archived item. it is generated dynamically when the item is indexed Prior to Enterprise Vault 10.x Enterprise Vault 9. In such cases the basic sender and recipient properties are available: 649 .0. using the Item object. Intra-site copying of archived items For intra-site copies. in accordance with the email address type from the following SMTP header fields: Sender: From Sent representing: Sender Primary recipients: To Carbon copy recipients: Cc Blind carbon copy recipients: Bcc Copying message items The Content Management API can be used to copy or move archived items either within an Enterprise Vault site or between sites. . the CopyTo method provides support of full fidelity copying of archived items.650 Understanding how Enterprise Vault archives and indexes messages Copying message items FROM: Display/friendly name (frdn) FROM: SMTP address (frsm) FROM: Other email address (frot) PP: Display/friendly name (ppdn) PP: SMTP address (ppsm) PP: Other email address (ppot) TO: Recipient display/friendly name (rtdn) TO: Recipient SMTP address (rtsm) TO: Recipient Other email address (rtot) CC: Recipient display/friendly name (rcdn) CC: Recipient SMTP address (rcsm) CC: Recipient other email address (rcot) BCC: Recipient display/friendly name (rbdn) BCC: Recipient SMTP address (rbsm) BCC: Recipient Other email address (rbot) The property values are completed with the message sender and recipient email address values. The second difference relates to copying Exchange envelope journal messages from Exchange journal archives. The best practice for moving archived items within a site is as follows: ■ Copy the items. The primary difference relates to the handling of sender and recipient details when indexing the archived items. “{API} Can Use Extended API Features” in both the source and destination sites.0 SP4 the properties are preserved if the account used to perform the copy is an Enterprise Vault role that includes the operation. From Enterprise Vault 8. the Get and Insert methods provide basic support for copying archived items. the copy is not a full fidelity copy because of the differences highlighted earlier in this appendix. See “IArchiveMetaData :: IsItemSecured” on page 237. ■ Wait for the destination items to be secured. and the domain directory for the destination site may not be the same as that for the source site. 651 . See “IArchiveMetaData :: IsItemSecured” on page 237. (as indicated by the IsItemSecured property of the ArchiveMetadata object). The default behavior is that the Message Sender and Recipients (sere) property and the Message Envelope Sender and Recipients (menv) property are not preserved. ■ Delete the source item. This operation is included in the Enterprise Vault Power Administrator and Storage Administrator roles.Understanding how Enterprise Vault archives and indexes messages Copying message items See “IItem :: CopyTo” on page 201. The best practice for moving archived items between sites is as follows: ■ Copy the items. ■ Wait for the destination items to be secured (as indicated by the IsItemSecured property of the ArchiveMetadata object). Inter-site copying of archived items For inter-site copies. Using the MoveTo method for intra-site moves is not recommended. as this deletes the source item before the destination item has been secured. The journal reports are not preserved when copying using the Get and Insert methods. ■ Delete the source item. They may potentially be regenerated at the destination site based on the destination site's environment and configuration. The archived item could be lost in a disaster recovery scenario. However. In addition. it is the Microsoft Structured Storage API that determines how the properties are persisted to a stream of bytes. For SMTP messages. which cannot be managed by Enterprise Vault. When Enterprise Vault copies the properties of the archived message back to a new instance of a Structured Storage. the properties of a message may be persisted using a variety of encoding schemes. such as quoted printable. Also. and binary. such as modified date. When the archived item is retrieved the same set of properties are present in the retrieved message. as the Microsoft MAPI API that is used to copy the properties adds or updates a number of "computed" properties. . For MAPI items. the behavior is the same as that already described for MAPI items . and then inserted into an NSF database. The main reason for this is that when the archived item is copied to a new instance of the message's external format. As the Enterprise Vault Note Stream format is based on the Microsoft Structured Storage format. Enterprise Vault may return SMTP items using an encoding scheme that differs from the original item. This format is based on the Microsoft Structured Storage format.652 Understanding how Enterprise Vault archives and indexes messages Why a retrieved item is not a binary copy of the original item Why a retrieved item is not a binary copy of the original item Enterprise Vault preserves the set of properties of message items that are archived and retrieved using the Content Management API. For Lotus Notes messages there is no native standalone file format. but the character set(s) typically remain unchanged. for example the archived item's Archive Id and Item Id. iso-8859-1. the Outlook Message Format is used as the persisted format of the message. Enterprise Vault may add Enterprise Vault specific properties to the retrieved item. Additional differences may be apparent. base64. Enterprise Vault cannot control how the message properties are persisted to a stream of bytes. different character sets may be used. for example utf-8. but it is not a binary copy of the original item. Windows-1252. so Lotus Notes messages have to be retrieved in Enterprise Vault Note Stream format. 7bit. Index A I AddProperty method ISearchQuery interface methods SearchQuery object 476 AddQuery method ISearchQuery interface methods SearchQuery object 481 Indexes updating 439 Indexing items 438 Indexing levels 442 IndexSearch2 object Search API SelectArchive method 505 interface methods AddProperty SearchQuery object 476 AddQuery SearchQuery object 481 SelectArchive IndexSearch2 object 505 SetProperty SearchQuery object 474 ISearchQuery interface methods AddProperty method 476 AddQuery method 481 SetProperty method 474 items compressing 438 converting 438 C compressing items 438 constants ESearchQueryFlags constant Search API 458 Converting items 438 Custom Filtering API get_defaultRetentionCategoryId methods IArchivingControl interface 366 ProcessFilter method IExternalFilter interface 359 E Enterprise Vault documentation 19 ESearchQueryFlags constant Search API 458 F File system filter reports 393 flags ESearchQueryFlags constant Search API 458 G get_defaultRetentionCategoryId methods IArchivingControl interface Custom Filtering API 366 granularity of search results attachment 444 item 444 M methods SelectArchive IndexSearch2 object 505 P ProcessFilter method IExternalFilter interface Custom Filtering API 359 S Search API ESearchQueryFlags constant 458 searches overview of performing a search 449 . 654 Index searches (continued) results. processing 452 SearchQuery object SearchQuery interface methods AddProperty 476 AddQuery 481 SetProperty 474 SelectArchive method IndexSearch2 object Search API 505 SetProperty method ISearchQuery interface methods SearchQuery object 474 .
Copyright © 2024 DOKUMEN.SITE Inc.