EV10 API Reference

Symantec Enterprise Vault™ Application Programmer's Guide

10.0

Symantec Enterprise Vault: Application Programmer's Guide The software described in this book is furnished under a license agreement and may be used only in accordance with the terms of the agreement. Last updated: 2012-02-27.

Legal Notice Copyright © 2012 Symantec Corporation. All rights reserved. Symantec, the Symantec Logo, Veritas, Enterprise Vault, Compliance Accelerator, and Discovery Accelerator are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners. This Symantec product may contain third party software for which Symantec is required to provide attribution to the third party (“Third Party Programs”). Some of the Third Party Programs are available under open source or free software licenses. The License Agreement accompanying the Software does not alter any rights or obligations you may have under those open source or free software licenses. Please see the Third Party Software file accompanying this Symantec product for more information on the Third Party Programs. The product described in this document is distributed under licenses restricting its use, copying, distribution, and decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior written authorization of Symantec Corporation and its licensors, if any. THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. SYMANTEC CORPORATION SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE. The Licensed Software and Documentation are deemed to be commercial computer software as defined in FAR 12.212 and subject to restricted rights as defined in FAR Section 52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS 227.7202, "Rights in Commercial Computer Software or Commercial Computer Software Documentation", as applicable, and any successor regulations. Any use, modification, reproduction release, performance, display or disclosure of the Licensed Software and Documentation by the U.S. Government shall be solely in accordance with the terms of this Agreement. Symantec Corporation 350 Ellis Street, Mountain View, CA 94043 http://www.symantec.com

Technical Support In order to develop software using Enterprise Vault APIs, your company must be a member of Symantec Technology Enabled Program (STEP). For details of the technical support available to you, refer to your STEP membership documentation, or contact the STEP office at [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

14

Contents

Chapter 7

Search API ........................................................................... 435 About Search API ....................................................................... About storing data in Enterprise Vault ........................................... Introduction to Enterprise Vault indexing ....................................... Index Servers and Index Server groups ..................................... About index volumes ............................................................. About indexing options ......................................................... About index properties .......................................................... Granularity of search results .................................................. Using the Search API .................................................................. Constructing a search query ................................................... ESQfilter searches ................................................................ Special characters in search queries ......................................... Performing a search .............................................................. Processing the search results .................................................. Enterprise Vault index properties ............................................ Search API example .............................................................. Constants and enumerations ........................................................ Index Property constants ....................................................... ESearchQueryFlags enumeration ............................................ ESearchQueryOperators enumeration ...................................... ESearchOperatorScope enumeration ........................................ EOptionsFlags enumeration ................................................... EPropertySets enumeration ................................................... ETruncationReason enumeration ............................................ EXMLResultsFormatOptions enumeration ................................ SearchQuery object ..................................................................... ISearchQuery :: Query ................................................................. ISearchQuery :: Clear .................................................................. ISearchQuery :: SetTerm .............................................................. ISearchQuery :: AddTerm ............................................................. ISearchQuery :: SetRange ............................................................. ISearchQuery :: AddRange ............................................................ ISearchQuery :: SetProperty ......................................................... ISearchQuery :: AddProperty ........................................................ ISearchQuery :: AddOp ................................................................ ISearchQuery :: Combine .............................................................. ISearchQuery :: AddQuery ............................................................ ISearchQuery2 :: SetPropertyRange ............................................... ISearchQuery2 :: AddPropertyRange .............................................. IndexSearch object ..................................................................... IIndexSearch2 :: IndexVolumeSets .................................................

438 438 439 439 441 442 443 443 445 446 448 449 449 452 453 453 457 457 458 459 459 460 460 461 461 462 464 465 466 468 470 472 474 476 478 479 481 482 484 485 489

Contents

IIndexSearch2 :: Options .............................................................. IIndexSearch2 :: SortBy ............................................................... IIndexSearch2 :: ResultsPropertySet .............................................. IIndexSearch2 :: AdditionalResultsProperties .................................. IIndexSearch2 :: Timeout ............................................................. IIndexSearch2 :: ArchiveEntryId ................................................... IIndexSearch2 :: ArchiveName ...................................................... IIndexSearch2 :: HasFolders ......................................................... IIndexSearch2 :: IndexVolumeSetIdentity ....................................... IIndexSearch2 :: IndexVolumeIdentity ............................................ IIndexSearch2 :: IndexVolumeSetCount .......................................... IIndexSearch2 :: MaxSearchIndexVolumeSets .................................. IIndexSearch2 :: MaxSearchResultsPerVolumeSet ............................ IIndexSearch2 :: SelectArchive ...................................................... IIndexSearch2 :: ListIndexVolumeSets ............................................ IIndexSearch2 :: SelectIndexVolumeSet .......................................... IIndexSearch2 :: SelectIndexVolume .............................................. IIndexSearch2 :: Search ............................................................... IIndexSearch2 :: SearchToXML ..................................................... IIndexSearch2 :: AddAdditionalResultsProperty ............................... IIndexSearch2 :: AddAdditionalResultsCustomProperty .................... IIndexSearch2 :: Reset ................................................................. IndexVolumeSets object .............................................................. IIndexVolumeSets :: ArchiveEntryId .............................................. IIndexVolumeSets :: ArchiveName ................................................. IIndexVolumeSets :: HasFolders .................................................... IIndexVolumeSets :: Count ........................................................... IIndexVolumeSets :: _NewEnum .................................................... IIndexVolumeSets :: Item ............................................................. IndexVolumeSet object ................................................................ IIndexVolumeSet :: Identity .......................................................... IIndexVolumeSet :: ArchiveEntryID ............................................... IIndexVolumeSet :: ArchiveName .................................................. IIndexVolumeSet :: FirstItemIndexSequenceNumber ........................ IIndexVolumeSet :: OldestArchivedDate ......................................... IIndexVolumeSet :: YoungestArchivedDate ..................................... IIndexVolumeSet :: OldestItemDate ............................................... IIndexVolumeSet :: YoungestItemDate ........................................... IIndexVolumeSet :: DateTimesUTC ................................................ SearchResults object ................................................................... ISearchResults :: Results .............................................................. ISearchResults :: Count ................................................................ ISearchResults :: Total .................................................................

490 491 493 494 495 497 497 498 499 500 501 502 504 505 506 508 510 511 514 517 518 519 519 521 522 522 523 524 525 527 528 529 530 531 531 532 533 534 534 536 538 539 540

15

16

Contents

ISearchResults :: Start ................................................................. ISearchResults :: Options ............................................................. ISearchResults :: SortBy ............................................................... ISearchResults :: _NewEnum ........................................................ ISearchResults :: Item .................................................................. ISearchResults2 :: InSync ............................................................. ISearchResults2 :: TruncationReason ............................................. ISearchResults2 :: DateTimesUTC .................................................. ISearchResults2 :: LoadResults ...................................................... SearchResult object .................................................................... ISearchResult :: Result ................................................................. ISearchResult :: Number .............................................................. ISearchResult :: Prop ................................................................... ISearchResult :: Prop2 ................................................................. ISearchResult2 :: Count ............................................................... ISearchResult2 :: Item ................................................................. ISearchResult2 :: DateTimesUTC ...................................................

Chapter 8

541 542 543 543 545 546 547 548 549 550 551 552 553 554 556 557 558

Retention API ...................................................................... 561 About Retention API ................................................................... Retention API ............................................................................ Components ........................................................................ Security .............................................................................. Enumerations ............................................................................ Retention Units enumeration ................................................. Retention Date Basis enumeration ........................................... RetentionCategories object ........................................................... IRetentionCategories :: Count ....................................................... IRetentionCategories :: _NewEnum ................................................ IRetentionCategories :: Item ......................................................... IRetentionCategories :: DirectoryDNSAlias ...................................... IRetentionCategories :: Lookup ..................................................... IRetentionCategories :: Create ....................................................... IRetentionCategories :: Add .......................................................... IRetentionCategories :: Update ...................................................... IRetentionCategories2 :: Get ......................................................... RetentionCategory object ............................................................. IRetentionCategory :: Period ......................................................... IRetentionCategory :: Units .......................................................... IRetentionCategory :: IsVisible ...................................................... IRetentionCategory :: Identifier ..................................................... IRetentionCategory :: Name ..........................................................

562 562 562 563 563 563 563 564 565 567 568 569 571 572 574 576 577 578 579 581 583 585 587

Contents

IRetentionCategory :: Description .................................................. IRetentionCategory :: OnHold ....................................................... IRetentionCategory :: Locked ........................................................ IRetentionCategory2 :: ExpiryBasis ................................................

Appendix A

Enterprise Vault properties ............................................. 595 About Enterprise Vault properties ................................................. System properties ...................................................................... Note 1 ................................................................................ Note 2 ................................................................................ Note 3 ................................................................................ Note 4 ................................................................................ Note 5 ................................................................................ Note 6 ................................................................................ Version information ............................................................. Defined custom properties ........................................................... Note 1 ................................................................................ Note 2 ................................................................................ Defined custom FSA properties ..................................................... Defined custom SharePoint properties ........................................... Defined properties for Compliance Accelerator ................................

Appendix B

595 596 609 609 610 610 611 612 613 614 615 615 616 616 617

API return values ............................................................... 619 About API return values .............................................................. Content Management API return values ......................................... Retention API return values ......................................................... Search API return values ............................................................. External Filter API Event log messages ........................................... Exchange Server filtering ...................................................... Domino Server filtering ......................................................... File System filtering ..............................................................

Appendix C

588 589 591 593

619 619 620 621 623 623 624 625

Understanding how Enterprise Vault archives and indexes messages ........................................................ 627 About storing and retrieving message items .................................... Exchange (MAPI) messages .......................................................... How the Enterprise Vault archiving agent processes Exchange mailbox messages ........................................................... How the Content Management API processes Exchange mailbox messages ......................................................................

627 628 628 633

17

18

Contents

How the Enterprise Vault archiving agent processes Exchange envelope journal messages ............................................... How the Content Management API processes Exchange envelope journal messages ............................................................ Lotus Notes messages .................................................................. How the Enterprise Vault archiving agent processes Lotus Notes mailbox messages ........................................................... How the Content Management API processes Lotus Notes mailbox messages ...................................................................... How the Enterprise Vault archiving agent processes Lotus Notes journal messages ............................................................ How the Content Management API processes Lotus Notes journal messages ...................................................................... SMTP messages ......................................................................... How the Content Management API processes SMTP messages ...................................................................... Copying message items ................................................................ Intra-site copying of archived items ......................................... Inter-site copying of archived items ......................................... Why a retrieved item is not a binary copy of the original item .............

640 640 641 641 645 646 647 648 648 650 650 651 652

Index ................................................................................................................... 653

Chapter

1

About this guide This chapter includes the following topics: ■

Introducing this guide

■

Enterprise Vault documentation

■

Comment on the documentation

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

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

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

20

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. Please include the following information with your comment: ■

The title and product version of the guide you are commenting on

■

The topic (if relevant) you are commenting on

■

Your name

Email your comment to [email protected]. Please only use this address to comment on product documentation. We appreciate your feedback.

Chapter

2

API updates This chapter includes the following topics: ■

About API updates

■

Enterprise Vault 10.0.1

■

Enterprise Vault 10.0

■

Enterprise Vault 9.0 SP3

■

Enterprise Vault 9.0

■

Enterprise Vault 8.0 SP5

■

Enterprise Vault 8.0 SP4

■

Enterprise Vault 8.0 SP3

■

Enterprise Vault 8.0 SP2

■

Enterprise Vault 8.0 SP1

■

Enterprise Vault 8.0

■

Enterprise Vault 7.0 SP4

■

Enterprise Vault 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

API updates About API updates

About API updates This chapter lists changes made to the APIs, SDK, or this API manual, and advance notice of future changes to Enterprise Vault APIs.

Enterprise Vault 10.0.1 This section lists the changes and corrections in Enterprise Vault 10.0.1. Table 2-1

Changes and corrections

Ref

Change details

E2595657

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

10788

Exchange Filtering API The IArchivingControl interface of the Exchange Filtering API has been extended to add a new method, IArchivingControl4 :: AddIndexedPropertyEx. This method accepts a VARIANT data structure when specifying string, integer and date custom index property values. This enables searching on date-based selection criteria. Use AddIndexedPropertyEx to add custom index properties instead of the methods, AddIndexedProperty, AddIndexPropertySet, and AddIndexPropertyToSet. See “IArchivingControl interface for Exchange filtering” on page 360.

API updates Enterprise Vault 10.0

Table 2-1

Changes and corrections (continued)

Ref

Change details

9912, E2478239

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

12266, E2603468

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

Enterprise Vault 10.0 This section lists the changes and corrections in Enterprise Vault 10.0. Note: Enterprise Vault 10.0 includes a new, 64-bit, indexing engine. To take advantage of the new indexing engine, Enterprise Vault now runs on 64-bit systems only. For more details of the indexing engine, see the Enterprise Vault 10.0 ReadMeFirst. If you run Enterprise Vault client application scripts on a 64-bit operating system, use the 32-bit version of command prompt, C:\Windows\SysWOW64\cmd.exe. Table 2-2

Changes to Filtering APIs

Ref

Change details

100-2538, 100-5024, 100-5049, 100-5743, 100-5815, 100-6252, CAS-6002

The File System Filtering API has been added to the Filtering APIs chapter. This API enables you to create external custom filters for File System Archiving tasks. The filters define how the archiving task selects and processes files. Two example filters that use the File System Filtering API are included in the SDK. The ReadMe file in the folder InstallFolder\sdk\samples\FSA Filter Sample describes the example filters and gives instructions on how to install and use them. See “Domino Filtering and File System Filtering APIs” on page 389.

23

24

API updates Enterprise Vault 10.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 .NET assembly: Symantec.EnterpriseVault.FilterInterfaces.dll The API interfaces are loaded within the namespace: Symantec.EnterpriseVault.FilterInterfaces

Note: If you have existing filters developed using the Domino Filtering API, then you need to rebuild the filters after upgrading to Enterprise Vault 10. References in the existing filters to the .NET assembly, KVS.EnterpriseVault.LotusDominoInterfaces.dll, must be redirected to the new .NET assembly, Symantec.EnterpriseVault.FilterInterfaces.dll. 100-6100

Table 2-3 Ref

When entering the registry setting value for a file system or Domino custom filter, the class name must include the namespace. The separator used between the assembly and the class name must be "!".

Changes to Search API Change details Federated searches can be performed across 32-bit and 64-bit indexes for customers upgrading from earlier releases. The following search operators are no longer supported for newly indexed items: begins with any of (ESQBeginany) begins with phrase (ESQBegins) is exactly any of (ESQExactany) ends with any of (ESQEndsany) ends with phrase (ESQEnds) automatically add wildcard to end of all words (ESQAutowild) Using these search operators against previously indexed items will continue to be supported. Indexing service now updates indexes every hour.

API updates Enterprise Vault 10.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). See “IIndexSearch2 :: Timeout” on page 495.

Table 2-4

Changes to Content Management API

Ref

Change details

E2082521

The Enterprise Vault system property, shct, is no longer supported.

100-5709

In the EV_STG_API_INDEX_LEVEL enumeration, INDEX_LEVEL_MEDIUM value is not supported on Enterprise Vault 10.0 servers. If medium level indexing is requested on an Enterprise Vault 10.0 server, then full indexing is implemented.

100-6261

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

100-7987

The sender and recipient indexing metadata and the Vault MsgDirection and Vault.MsgType custom index properties that are associated with SMTP messages (.eml files) and Digitally Signed MAPI messages (.msg files, message class "IPM.Note.SMIME.MultipartSigned") are now stored on item insert operations. They are also preserved when performing copy or move item operations using the Content Management API. In earlier releases this functionality only applied to regular MAPI messages (.msg files, message class "IPM.Note") that were ingested using the Content Management API. See “Defined custom properties” on page 614.

100-6424

When attempting to retrieve items from slow devices, Enterprise Vault reported timeouts and a fatal internal error. In such circumstances, Enterprise Vault now returns the temporary error, CONTENTMANAGEMENTAPI_E_BUSY, so that the application can retry the retrieval after a sleep period.

25

26

API updates Enterprise Vault 9.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, but no index locations have been configured for the archive. Use the ExtendedErrorInfo object to access detailed error information.

100-7796

A new ReadMe file is included with the Content Management API example application (in the folder InstallFolder\samples\ECM API Sample). The ReadMe provides a description of the application, and gives instructions on how to install and use it.

Table 2-5

Documentation change

Ref

Change details

100-9330, E2365577

A new appendix has been added to this manual. This appendix provides information on the following topics: How the Content Management API processes message items. In particular, how Enterprise Vault processes sender and recipient details for different message types, and key changes over recent releases of Enterprise Vault. ■ Why a retrieved item is not a binary copy of the original item. ■

■

Using the Content Management API to migrate Enterprise Vault archived messages from one Enterprise Vault installation to another.

See “About storing and retrieving message items” on page 627.

Enterprise Vault 9.0 SP3 This section lists the changes and corrections made for Enterprise Vault 9.0 SP3. 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. See “EV_STG_API_CP_SETBY enumeration” on page 79.

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

API updates Enterprise Vault 8.0 SP5

Table 2-7 Ref

Changes to Content Management API Change details MSXML 6.0 or later is now required on the computer where you install the Enterprise Vault API runtime.

900-1652

Guidance on thread priority has been added. See “General guidelines for using the API” on page 69.

900-2524

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

900-2677

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

2050482

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

Enterprise Vault 8.0 SP5 This section lists the changes and corrections made for Enterprise Vault 8.0 SP5. Table 2-8

Changes to Content Management API

Ref

Change details

8053386, E2030385

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

27

28

API updates Enterprise Vault 8.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. See “ISimpleIndexProperty :: Value” on page 275.

Table 2-9

Changes to Filtering APIs

Ref

Change details

8054561, E2096343

HARD_DELETE is now available as an option in the Domino action enumeration. See “EV_ACTION enumeration” on page 356.

E1980890

The following sections have been expanded to provide more information on the filtering registry settings: See “Exchange filtering registry settings” on page 352. See “Domino filtering registry settings” on page 394.

E2095734

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

Table 2-10

Changes to Enterprise Vault properties

Ref

Change details

E2027779

Added the property, Vault.CopiedFrom, to the list of custom properties defined in Enterprise Vault. This property provides details for items that have been copied by Move Archive. See “Defined custom properties” on page 614.

API updates Enterprise Vault 8.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.

Enterprise Vault 8.0 SP4 This section lists the changes and corrections made for Enterprise Vault 8.0 SP4. 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. See “IContent :: FileExtension” on page 215.

E1533874

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

E1669297

The description of the EV_STG_API_ITEM_DETAIL enumeration has been expanded to show the properties that are returned for the different enumeration values. See “EV_STG_API_ITEM_DETAIL enumeration” on page 83.

804-1613, E1948433

When using the CopyTo function, the source item's Sender/Recipients P1 data was not retained and merged with any specified custom index properties for adding to the destination/copied item. This has been fixed.

29

30

API updates Enterprise Vault 8.0 SP3

Table 2-11

Changes to Content Management API (continued)

Ref

Change details

8041728, E1950563

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

Table 2-12

Changes to Search API

Ref

Change details

E1448964

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

Enterprise Vault 8.0 SP3 This section lists the changes and corrections made for Enterprise Vault 8.0 SP3. Table 2-13

Changes to Content Management API

Ref

Change details

803151

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

803137

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

API updates Enterprise Vault 8.0 SP3

Table 2-13 Ref

Changes to Content Management API (continued) Change details

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

The S_FALSE return value has been documented for the following object properties. ■

IItem::Id

■

IContent::OriginalLocation

■

IArchiveMetaData::RetentionCategory

■

IArchiveMetaData::CustomIdentifier

■

IArchiveMetaData::CustomQualifier

■

ArchiveMetaData::CustomProperties

■

IArchiveMetaData2::CurrentLocation

■

IArchiveMetaData2::CurrentFolderId

■

IArchiveMetaData2::ArchivedDate

These properties can return the default property value and an S_FALSE return value when reading the property before it has been written. This is a success return value. When coding in C++ the S_FALSE return value should be handled using the Windows SUCCEEDED or FAILED macros. 803587, E1737966 When populating very large Archives collection objects, the value of the Maximum property (the maximum number of records that can be returned) was not honored. As a result, the operation failed, and insufficient resource errors were reported. This has been fixed. 803125, E1726196, Sometimes files of between 5 MB and 50 MB were truncated when E1739537 retrieved using the Content Management API . This has been fixed.

31

32

API updates Enterprise Vault 8.0 SP2

Table 2-13 Ref

Changes to Content Management API (continued) Change details

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

Enterprise Vault 8.0 SP2 This section lists the changes and corrections made for Enterprise Vault 8.0 SP2. Table 2-14

Changes to Content Management API

Ref

Change details

802168

A new interface, IExtendedErrorInfo, has been added. This interface provides extended error information if an error is encountered when using the Content Management API methods. See “ExtendedErrorInfo object” on page 316.

802077

EV_STG_API_AUTHENTICATE_USING enumeration has new value added: AUTHENTICATE_USING_MOST_APPROPRIATE_MODE See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 77.

802559, E1703228, IContent::Title no longer needs to be populated before calling Insert. E1639951 See “IItem :: Insert” on page 191. 802577, E1476982, IArchive::Name and IArchive::Description can contain printable, E1600648 Unicode characters. IArchive::Name is mandatory and cannot be blank or an empty string. IArchive::Description is optional. See “IArchive :: Name” on page 133. See “IArchive :: Description” on page 134.

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

API updates Enterprise Vault 8.0 SP1

Table 2-15

Changes to Content Management API

Ref

Change details

8010032

The new value, ITEM_COPYOPTIONS_MERGE_INDEXMETADATA, has been added to the EV_STG_API_ITEM_COPYOPTIONS enumeration. This enables additional custom index metadata properties on the source item to be added to existing custom index metadata properties on the destination item. See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 82.

8010141

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

8010204, E1422959

If the source archive was in a read-only state, CopyTo failed and returned the error CONTENTMANAGEMENTAPI_E_BUSY. This has been fixed. Further changes have been made to support situations where an archive is in a read-only state. The error CONTENTMANAGEMENTAPI_E_NO_ACCESS (Status code = 0x80040303) is now returned when the following actions are attempted: Copying an item when the destination archive is in a read-only state. ■ Moving an item when the source or destination archive is in a read-only state. ■ Inserting, deleting, or changing the retention period for an item when the archive is in a read-only state. ■

In addition, the IItem::CanBeDeleted property value will indicate DELETE_ACCESS_DENIED for items located in an archive which is in a read-only state. 8010139

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

33

34

API updates Enterprise Vault 8.0

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

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

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

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

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

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

API updates Enterprise Vault 8.0

Content Management API 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. See “IContentManagementAPI3 :: IDispatchQueryInterface” on page 104.

BAU0819

■

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

BAU0819

■

The EV_STG_API_PERMISSIONS_TYPE enumerator is now used in place of the DV_DS_E_PERMISSION enumerator when creating the security descriptor for use with IArchive::SecurityDescriptor.

BAU2464 BAU0225

A new interface, IItems, has been added to facilitate the enumeration of items in an archive. See “Enumerating vault stores, archives and items” on page 70.

35

36

API updates Enterprise Vault 8.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; the item content and its associated ArchiveMetaData and IndexData elements are copied from the source item to the destination item. This means that the new default behaviour preserves the original ArchivedDate and OriginalLocation on the destination item, if override values are not specified. For backwards compatibility, the calling application can set suitable override values on the destination item object. ■ A new CopyOptions property identifies the source item property values to be copied to the destination item when copying or moving items. Override values can be set for specific Item properties. See “IItem :: CopyOptions” on page 187.

BAU0378

■

IArchiveMetaData2 provides additional properties for determining the archive folder location of an item: ■ The CurrentLocation or CurrentFolderId properties identify the archive folder in which the item is stored, or to be stored. See “IArchiveMetaData2 :: CurrentLocation” on page 245.

BAU0378

■

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

BAU778

■

A new read/write IArchiveMetaData2::ArchivedDate property enables the caller to set the UTC date and time when an item was stored. To prevent unauthorized users, who have write access to an archive, from changing the archived date of an item, the calling application must run under an account assigned to the Enterprise Vault Power Administrator role or Storage Administrator role.

BAU0795 BAU1179

API updates Enterprise Vault 8.0

Table 2-16

Changes to Content Management API (continued)

Ref

Change details

BAU1179

■

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

BAU1761

■

IHold::ItemId property value can now be a valid Saveset Id or Transaction Id. See “Saveset IDs and Transaction IDs” on page 71.

BAU1473

■

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

BAU1796

■

BAU2013

■

BAU2853

Enhancements to the API mean that .NET applications no longer need to call CoInitializeSecurity when remotely accessing IStream or IlockBytes objects containing large items (larger than 4MB). ■ The Content Management API threading model has been changed from COM single-threaded apartment (STA) to Both, thus simplifying use in .NET applications. MSXML 3.0 is now the minimum version of MSXML required on the computer where you install the application using the Content Management API.

37

38

API updates Enterprise Vault 8.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. Added the following interfaces, method and property: IRetentionCategories2 Improved the retrieval of retention category details by providing a Get method. ■ IRetentionCategory2 Provides ExpiryBasis property for determining date from which storage expiry is calculated. ■

Migration API Table 2-18

Change to Migration API

Ref

Change details

BAU2485

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

New index properties added Table 2-19

New index properties

Ref

Index property name

Description

BAU0585

crct

Current Retention Category Id, searchable and retrievable

BAU0931

clcn

Current location, retrievable only

cllf

Current leaf folder name, retrievable only

clfn crcn

Current location folder names, retrievable only Current Retention Category name, retrievable only

API updates Enterprise Vault 7.0 SP4

Table 2-19

New index properties (continued)

Ref

Index property name

Description

BAU1320

cnhv

Conversation Hierarchical View, retrievable only

BAU1426

fpdd

Index Fingerprint of item, searchable and retrievable

fpcn

Index Fingerprint of content, searchable and retrievable

Corrections Table 2-20

Corrections

Ref

Change details

1088101, 847952

The Storage service is no longer accessed when enumerating archives.

1204891

The IContent::OriginalLocation property is now preserved when performing a copy or move operation.

1271036

Description of IArchiveMetaData::RetentionExpires property has been clarified. This property is for use with compliance devices, and requires the item detail level set to DETAIL_LEVEL_COMPLIANCE_DATA.

Enterprise Vault 7.0 SP4 This section lists the changes and corrections made for Enterprise Vault 7.0 SP4. Table 2-21

Corrections

Ref

Change details

E1107082

Updated description of IContent::FileExtension. See “IContent :: FileExtension” on page 215.

E1143215

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

E1167957

Updated information about supported combinations of properties in Archives object. See “Archives object” on page 119.

39

40

API updates Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5

Table 2-21

Corrections (continued)

Ref

Change details

E1185396

Added IContentManagementAPI2 :: VaultStore. See “IContentManagementAPI2 :: VaultStore” on page 101.

E1187820

Corrected description of ISimpleIndexMetadata :: Count. See “ISimpleIndexMetadata :: Count” on page 261.

E1188342

Corrected description of IItem :: CanBeDeleted. See “IItem :: CanBeDeleted” on page 200.

E1191078

Added example format for the consumer GUID in IHold :: ConsumerGUID. See “IHold :: ConsumerGUID” on page 306.

E1193018

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

E1196051

Updated description of ComplianceData object to note that it is for use only with compliance devices, and updated Return values for IArchiveMetaData :: Update. See “ComplianceData object” on page 281. See “IArchiveMetaData :: Update” on page 243.

E1203217

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

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

API updates Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5

Table 2-22

Changes and corrections

Ref

Change details

751207, 703021, 605047

■

751208, 703020, 605036

■

751127, 703010

■

Availability

New sere index property. This Enterprise Vault 6.0 SP5, property returns sender and Enterprise Vault 7.0 SP3, recipient details from the Enterprise Vault 2007 SP1 message header (P2) if the archived item is a message. See Table A-1 on page 596. ■ menv index property changes. This property is now only returned for journaled messages. It returns sender recipient details from the message envelope (P1) if the archived item is an envelope message. See Table A-1 on page 596. New interface for Exchange Enterprise Vault 6.0 SP5, filtering, IArchvingControl3, Enterprise Vault 7.0 SP3, to retrieve sender and Enterprise Vault 2007 SP1 recipient information as XML. See “IArchivingControl interface for Exchange filtering” on page 360.

SimpleIndexProperty object: Enterprise Vault 7.0 SP3, 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. See “ISimpleIndexProperty :: Name” on page 272. ■ menv index property: This property now includes the message sender/author and delegate sender (if applicable) encoded in the element. See Table A-1 on page 596.

41

42

API updates Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4

Table 2-22

Changes and corrections (continued)

Ref

Change details

751143, 703011

■

Availability

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

703038, E1143932 ■ IArchive::Create: updated description of properties and examples. See “IArchive :: Create” on page 149.

Enterprise Vault 7.0 SP3, Enterprise Vault 2007 SP1

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

API updates Enterprise Vault 2007, Enterprise Vault 7.0 SP2, 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, IVaultStores, IVaultStore, IArchives, IArchive2, ICollectionBase. These interfaces supersede the functionality previously provided by the unsupported EnumVaultsByMe method. ■ DirectoryDNSAlias property in the Content Management API and Retention API has been enhanced to accept input of any Enterprise Vault id, such as, archive Id, retention category Id, vault store Id. ■ New IDiagnosticsAPI interface added to Content Management API to enable application integration tracing using Enterprise Vault diagnostic tools. Simple API removed from API Enterprise Vault 2007 Guide. Refer to previous releases of the manual for this deprecated API. ■ Migration API included in API Guide. ■ Integrating third-party messaging removed and now available as a tech note from Enterprise Vault support knowledge base. ■ Provisioning API removed. This will be incorporated in the Utilities Guide at a future release.

43

44

API updates Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4

Table 2-23

Changes and corrections (continued)

Ref

Change details

702045, 604133, E974294

■

702045, 604133

■

Availability

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

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

API updates Enterprise Vault 7.0

Enterprise Vault 7.0 This section lists the changes and corrections made for Enterprise Vault 7.0. 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.

Enterprise Vault 7.0

CAP433

■

An API license is no longer required in order to develop applications against the Enterprise Vault APIs.

Enterprise Vault 7.0

CAP463

■

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

CAP545, CAP721, E804597

■

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

CAP525

■

IContentManagementAPI has Enterprise Vault 7.0 a new property: AuthenticationMode, which specifies the mode of authentication to be used when the calling application contacts Enterprise Vault.

E775452

Availability

45

46

API updates Enterprise Vault 7.0

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. These can be used by applications to access Enterprise Vault functionality.

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

48

Enterprise Vault API overview Overview of Enterprise Vault APIs

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

Enterprise Vault APIs

API

Description

Content Management API

■

Create archives.

■

Enumerate collections of vault stores, archives or items.

■

Get properties of vault stores and archives.

■

List the items in an archive.

■

Store, retrieve, copy, move and delete archived items.

■

Get item properties.

■

Add custom index metadata to an item as it is stored.

Place holds on a group of items to prevent items from being deleted manually or by Enterprise Vault storage expiry. (Legal Hold) ■ Remove any holds placed on items. (Legal Hold) ■

Archives and vault stores cannot be deleted using the Content Management API. NSF Manager API

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

Search API

■

Search Enterprise Vault indexes.

Retention API

■

Create new retention categories.

■

Enumerate retention categories.

■

Set locks on a retention category.

■

Update an existing retention category.

■

Look up an existing retention category.

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

Select certain items for processing (and possibly archiving), based on attributes (for example, subject text, sender). ■ Store selected items in specific archives. ■

■

Set a particular retention category on selected items.

■

Delete selected items without archiving them.

■

Add custom index metadata to selected items before they are archived.

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

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

49

50

Enterprise Vault API overview Licensing

Licensing No additional Enterprise Vault license is required in order to develop applications against the Enterprise Vault APIs. However, customer deployments of third-party applications which make use of the Enterprise Vault APIs will require the following license, in addition to any third party licensing requirements: ■

Symantec Enterprise Vault Custom Archiving Agent license (Enterprise Vault 8.0)

■

Symantec Generic Ingest Agent license (Enterprise Vault 2007)

This section describes the licensing requirements for the Enterprise Vault APIs.

Development licensing The Enterprise Vault APIs described in this guide are for developers who wish to add and/or manage content in Enterprise Vault archives. In most circumstances, these developers would be granted a Not for Resale (NFR) license to develop to these APIs by membership of Symantec Technology Enabled Program (STEP). Customers who wish to develop applications that integrate to these APIs would need to purchase one of the following licenses and request access to the Enterprise Vault SDK: ■

Symantec Enterprise Vault Custom Archiving Agent license (Enterprise Vault 8.0 or later) for ingesting content into Enterprise Vault. This license also covers management of content archived by Enterprise Vault.

■

Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault 8.0 or later) for management of content archived by Enterprise Vault.

■

Symantec Generic Ingest Agent license (Enterprise Vault 7.0 and Enterprise Vault 2007) for ingesting content into Enterprise Vault. This license also covers management of content archived by Enterprise Vault.

■

Symantec Generic Content Management Connector license (Enterprise Vault 7.0 and Enterprise Vault 2007) for management of content archived by Enterprise Vault.

Production licensing The STEP licensing contract does not grant production use of the Enterprise Vault APIs. Customer deployments of third-party applications and customer-developed applications that make use of the Enterprise Vault APIs will require one of the following licenses, in addition to any third-party licensing requirements:

Enterprise Vault API overview Deploying an application that uses the API

■

Symantec Enterprise Vault Custom Archiving Agent license (Enterprise Vault 8.0 or later) for ingesting content into Enterprise Vault. This license also covers management of content archived by Enterprise Vault.

■

Symantec Enterprise Vault ECM/RM Connector license (Enterprise Vault 8.0 or later) for management of content archived by Enterprise Vault.

■

Symantec Generic Ingest Agent license (Enterprise Vault 7.0 and Enterprise Vault 2007) for ingesting content into Enterprise Vault. This license also covers management of content archived by Enterprise Vault.

■

Symantec Generic Content Management Connector license (Enterprise Vault 7.0 and Enterprise Vault 2007) for management of content archived by Enterprise Vault.

Deploying an application that uses the API This section describes API runtime and .NET considerations when deploying applications that use the Enterprise Vault API runtime.

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

Checking the API runtime version and the installation path The application should verify that version of the runtime installed on the local computer is compatible with the application. For example, if the application uses Enterprise Vault 8.0 features, then the API runtime must be Enterprise Vault 8.0 or later.

51

52

Enterprise Vault API overview Deploying an application that uses the API

If you are using Enterprise Vault 8.0 or later, the application can query registry settings directly to find out the the version of the Enterprise Vault API runtime installed locally and the installation path. The registry settings to query are InstallPath and Version in the following location: HKEY_LOCAL_MACHINE \Software \KVS \Enterprise Vault \API Runtime \Install

On 64-bit versions of Windows Server, the Enterprise Vault registry settings are under the following location: HKEY_LOCAL_MACHINE \Software \WOW6432node \KVS

If you are using a version of Enterprise Vault prior to Enterprise Vault 8.0, follow the instructions given in Checking version and installation path details prior to Enterprise Vault 8.0.

Checking version and installation path details prior to Enterprise Vault 8.0 To detect if Enterprise Vault API runtime libraries, or the Enterprise Vault SDK, are installed locally, and find out the installation location, you can use the Windows Installer API: ■

Use the FindRelatedProducts action and the Upgrade Table to locate products with the following UpgradeCodes: {2FEB3523-3A2C-4518-A0D4-BD38E66A5E8C} — Enterprise Vault runtime {C8486BDD-85C4-48CC-97BA-82F1079DA61E} — Enterprise Vault SDK

■

When you have ascertained that either of these is installed, you can use the MsiGetProductInfo method and the relevant product code to find out the installation location (INSTALLPROPERTY_INSTALLLOCATION) of the runtime or SDK.

To detect if Enterprise Vault server is installed, and find out the installation location, you can query the following registry settings directly: ■

HKEY_LOCAL_MACHINE \Software \KVS

Enterprise Vault API overview Deploying an application that uses the API

\Enterprise Vault \Install \VaultServices

If the value of this setting is "Installed", then Enterprise Vault server is installed. ■

HKEY_LOCAL_MACHINE \Software \KVS \Enterprise Vault \Install \InstallPath

Deploying .NET applications When deploying a .NET application, the application must ensure that suitable versions of the Interop assemblies for Enterprise Vault API components have been installed. This is best done in one of the following ways: ■

The application can be built against the set of Primary Interop Assemblies (PIAs) in the Enterprise Vault SDK. When the application is deployed, it must be configured to use the PIAs provided by the Enterprise Vault API runtime.

■

This requires an application configuration file with entries for each of the Enterprise Vault API components used by the application. The assembly redirections must include a element that defines the location of the PIA and, optionally, a element if the application is built against a different PIA version to the one deployed by the Enterprise Vault runtime. See “Updating binding redirections in configuration files” on page 54.

■

Alternatively, the application generates, builds against, and deploys a set of Interop assemblies for those Enterprise Vault API components that are used by the application. The Interop assemblies can be generated indirectly using Visual Studio as part of the application build, or directly using the Microsoft .NET Framework Type Library Importer tool (tlbimp.exe). For example: tlbimp /nologo EVContentManagementAPI.dll

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

53

54

Enterprise Vault API overview Installing the Enterprise Vault SDK

Updating binding redirections in configuration files This section provides instructions on how to update the .NET application configuration files to use a newer version of the Enterprise Vault API runtime. To update the application configuration file:

1

Open the client application's configuration file, locate the Enterprise Vault nodes, and update any and 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:

2

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

Installing the Enterprise Vault SDK The Enterprise Vault SDK is distributed as a Windows installer kit, Symantec Enterprise Vault Software Development Kit.msi, which installs the following: ■

Enterprise Vault API runtime libraries

■

API samples

■

This manual in PDF and CHM format

Enterprise Vault API overview Installing the Enterprise Vault SDK

Checking the SDK version and installation path If you are using Enterprise Vault 8.0 or later, you can query the registry settings InstallPath and Version in the following location to find out the the version of the Enterprise Vault API SDK installed and the installation path: HKEY_LOCAL_MACHINE \Software \KVS \Enterprise Vault \Software Development Kit \Install

On 64-bit versions of Windows Server, the Enterprise Vault registry settings are under the following location: HKEY_LOCAL_MACHINE \Software \WOW6432node \KVS

If you are using a version of Enterprise Vault prior to Enterprise Vault 8.0, follow the instructions given elsewhere. See “Checking version and installation path details prior to Enterprise Vault 8.0” on page 52.

SDK examples The following examples are included in the SDK: ■

An example application for the Content Management API is installed in the folder, InstallFolder\samples\ECM API Sample. This application provides a UI that enables you to test out API functions such as creating an archive, storing an item in an archive, retrieving items, and viewing properties on items and archives. A ReadMe file in the folder provides instructions on how to install and use the application.

■

Two example filters that use the File System Filtering API are installed in the folder, InstallFolder\samples\FSA Filter Sample. A ReadMe file in the folder provides instructions on how to install and use the filters. ■

Example filter 1 (SampleFilter.cs) configures different actions for the File System Archiving task, depending on a variety of file properties. For example, one action is to delete files with any of the extensions, mp3, avi, or mpeg.

55

56

Enterprise Vault API overview Programming notes

■

Example filter 2 (CustomProp.cs) configures the File System Archiving task actions for Microsoft Office 2007 files that have custom properties added.

Programming notes ■

As the API interfaces are derived from IDispatch, they can be used by scripting languages.

■

The APIs can be used from C++, .NET languages (such as Visual Basic .NET and C#), ASP web pages (using Visual Basic Script), and other languages that support COM.

■

When running scripts on a 64-bit operating system, use the 32-bit version of command prompt, C:\Windows\SysWOW64\cmd.exe.

■

For best performance in a multi-threaded application, use a separate instance of an API object, such as a Content Management API object, per thread.

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

To exclude use of smart pointers, error wrapper functions and the EVContentManagementAPILib namespace: #import "EVContentManagementAPI.dll" no_namespace, raw_interfaces_only

Using Enterprise Vault APIs in .NET managed languages When using .NET managed languages to build an application using an API, Interop assemblies provide the .NET definitions for the API COM type library. You can reference the SDK Primary Interop Assemblies (PIAs), the COM API library or Interop assemblies generated via tlbimp, depending upon the deployment model selected. See “Deploying .NET applications” on page 53.

Enterprise Vault API overview Programming notes

The Primary Interop Assemblies (PIAs), COM API libraries or Interop assemblies should be added to the project's references to provide definitions of the COM classes, interfaces and types. For example, to reference the Content Management API via its PIA, add : KVS.EnterpriseVault.Interop.EVContentManagementAPI.dll

When referencing a PIA the API types are defined in the namespace KVS.EnterpriseVault.Interop.

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

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

Code samples In the code samples given in this manual, attention has been paid to the API specifics only. Other programming aspects, such as error handling, have been omitted for clarity. In general, code samples are included for C++ and C#. As Visual Basic .NET is very similar to C#, separate examples are not included in most cases.

57

58

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

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. When working with Lotus Notes databases, you can use the NSF Manager API to manage NSF databases, and import archived notes into a database or extract notes to be archived from a database. You can use the Content Management API to store notes in the archive or retrieve notes from the archive.

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

Content Management API About the Content Management API

Figure 4-1

Hierarchy of Content Management API objects

ContentManagementAPI









VaultStores

Archives

Items

Holds

VaultStore

Archive

Item

ArchiveMetaData

ComplianceData

Hold

Content

SimpleIndexMetadata

ExtendedErrorInfo

DiagnosticsAPI

SimpleIndexProperty

All the objects shown are exposed by the Content Management API:

67

68

Content Management API About the Content Management API

■

The ContentManagementAPI object provides a means of accessing the other objects, such as VaultStores, VaultStore, Archives and Item. These objects enable the examination of vault stores and archives in Enterprise Vault.

■

The VaultStores object enables applications to enumerate the vault stores configured in an Enterprise Vault site.The VaultStores object exposes a standard COM collection interface that manages a collection of VaultStore objects.

■

The Archives object enables applications to enumerate archives in a vault store. The properties enable the selection of archives using a combination of archive name, type and permissions. The Archives object exposes a standard COM collection interface that manages a collection of Archive objects.

■

The Archive object enables the creation of archives in an Enterprise Vault vault store.

■

The Items object enables applications to enumerate the items in an archive in batches. The Enterprise Vault index sequence number of an archived item is used to determine the first item in a batch. An Items collection can be enumerated by increasing the index sequence number (oldest archived item first), or by decreasing the index sequence number (most recently archived item first). The Items object exposes a standard COM collection interface that manages a collection of Item objects.

■

The Item object provides applications with a way to store and manage items in Enterprise Vault archives. The following interfaces are implemented by the Item object:

■

■

IContent interface provides calling applications with a set of properties that describe the data being archived or retrieved.

■

IArchiveMetaData interface provides calling applications with a set of properties that describe how the item is archived. The following interfaces are exposed by IArchiveMetaData: IComplianceData interface describes the compliance metadata set on an item in an archive. ISimpleIndexMetadata interface enables the calling application to add custom index metadata to an object as it is archived. This can then be searched for using the Search API.

The Holds object provides calling applications with the ability to place or release legal holds on multiple items at a time with a single call to the Enterprise Vault server. It exposes a standard COM collection interface that manages a collection of IHold objects. ■

The Hold object describes a hold that is placed on an item.

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.

■

The DiagnosticsAPI object enables calling applications to use the Enterprise Vault tracing utility, Dtrace, and write to the Enterprise Vault event log.

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

Use of objects It is best practice for the calling application to keep the ContentManagementAPI object alive as long as possible, as the ContentManagementAPI object caches information from Enterprise Vault, and frequent creation and release would result in poor performance of the client. Most of the object instances obtained from the ContentManagementAPI object are designed to be used only once. This prevents reuse of stale data. Once an object instance has been used (that is, Get, Insert or Create have been called), it can only be used for querying properties, not for setting them. Before any of these methods (Get, Insert or Create) can be called again, the existing object instance should be released and a new one obtained. For example, the following steps are required when storing an item in an archive: ■

Obtain an instance of an empty Item object by calling IContentManagementAPI::Item.

■

Populate its properties (ArchiveId, ArchiveMetaData, Content etc.).

■

Call the Insert method.

69

70

Content Management API General guidelines for using the API

■

Retrieve the item's Id from the object property.

■

Release the Item object instance. You cannot just repopulate the properties and call Insert again. If you attempt to do so an error will be reported.

A number of object properties, for example Item.Id, return the default property value and an S_FALSE return value when reading the property before it has been written. This is a success return value. When coding in C++ the S_FALSE return value should be handled using the Windows SUCCEEDED or FAILED macros. When coding in C# it is not possible to differentiate between the S_OK and S_FALSE return values.

Enumerating vault stores, archives and items Archives are held in vault stores, and items are held in archives. When storing or retrieving items using the Content Management API, or searching for archived items using the Search API, calling applications need to be able to find target vault stores and archives. This functionality is provided by the IVaultStores and the IArchives interfaces. These interfaces enable calling applications to enumerate and select vault stores and archives, and retrieve information about these from the Enterprise Vault Directory. The IItems interface enables the application to enumerate the items in an archive, and retrieve information about these items from the Enterprise Vault Storage Service. The IVaultStores, IArchives and IItems interfaces inherit the properties and methods of a generic collection enumeration interface, ICollectionBase. How to use this interface follows the general model for enumerating objects: ■

Obtain an empty collection instance from the ContentManagementAPI.

■

Populate the selection criteria properties.

■

Invoke the Get method to populate the collection.

■

Enumerate through the collection.

You can select archives using the following criteria: ■

By vault store; optionally filtered by archive type.

■

By name or partial name; optionally filtered by archive type.

■

By caller's access permissions; optionally filtered by archive type. For example, all FSA archives that the caller has permission to search.

■

By archive type.

With vault stores, you can only select all vault stores in an Enterprise Vault Site.

Content Management API General guidelines for using the API

You select items using the following criteria: ■

By archive.

■

By start item Index Sequence Number (ISN); optionally in ascending or descending order.

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

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

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

71

72

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. The appendix includes information about how Enterprise Vault processes sender and recipient details when archiving and retrieving messages, and copying or moving archived messages. Details are given for the different types of messages supported. See “About storing and retrieving message items” on page 627.

Adding custom index metadata Applications can add custom index metadata to an item as it is archived. When the item is indexed, this custom metadata will be included in the index for the item. The Search API can then be used to search archives for items with the custom information. When an archive is searched, the search is performed on the index associated with the archive, not on the archive itself. Note that custom index metadata properties cannot be added to attachments. Figure 4-2 illustrates how custom index metadata is added to an item using the Content Management API.

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, or one of the Filtering APIs: ■

In the Content Management API, use the methods on the ISimpleIndexMetadata interface. See “SimpleIndexMetadata object” on page 256. See “IArchiveMetaData :: IndexData” on page 236.

■

In the Exchange Filtering API, use the method IArchivingControl4 :: AddIndexedPropertyEx. Custom filtering is available for Exchange Mailbox Archiving Tasks, Exchange Public Folder Tasks and Exchange Journaling Tasks. See “IArchivingControl interface for Exchange filtering” on page 360.

■

In the Domino Filtering API and File System Filtering API, use the Add method in the IndexMetadata class. See “IArchivingControl interface” on page 402.

73

74

Content Management API General guidelines for using the API

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

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

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

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.MoveTo will support two audit entries; one for the item insertion and another for the item deletion from the original location.

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

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

EV_API_DELETION_LEVEL enumeration Deletion level enumeration defines the type of delete permitted for archived items: enum EV_API_DELETION_LEVEL { DELETION_LEVEL_SOFT_DELETE = 0, DELETION_LEVEL_HARD_DELETE = 1 };

Items can be deleted completely (hard delete), or moved to the Enterprise Vault "dumpster" area (soft delete). The default value is DELETION_LEVEL_SOFT_DELETE.

75

76

Content Management API Enumerations

In the Enterprise Vault Administration Console, in the Site Properties pages, the administrator can enable the recovery of deleted items and specify how long soft-deleted items are to be kept. This enumeration value is set using the Item DeletionLevel property. See “IItem :: DeletionLevel” on page 185.

EV_API_EVENT_TYPE enumeration Event type enumeration indicates the type of event: enum EV_API_EVENT_TYPE { EVENT_TYPE_ERROR = 1, EVENT_TYPE_WARNING = 2, EVENT_TYPE_INFORMATION = 3, EVENT_TYPE_SUCCESS_AUDIT = 4, EVENT_TYPE_FAILURE_AUDIT = 5 };

When an application creates a diagnostic message in the Enterprise Vault event log using the DiagnosticsAPI LogEvent method, this value indicates the type of message to create. See “IDiagnosticsAPI : LogEvent” on page 325.

EV_API_ITEMS_ORDERBY enumeration Items collection order defines whether to increase or decrease the index sequence number when enumerating a collection of items. enum EV_API_ITEMS_ORDERBY { ITEMS_ORDERBY_ASC = 0, ITEMS_ORDERBY_DESC = 1 };

The default value is ITEMS_ORDERBY_ASC; items are enumerated using ascending index sequence number order. See “IItems :: OrderBy” on page 170.

EV_API_TRACE_LEVEL enumeration Trace level enumeration indicates the trace level:

Content Management API Enumerations

enum EV_API_TRACE_LEVEL { TRACE_LEVEL_HIGH = 1, TRACE_LEVEL_MEDIUM = 2, TRACE_LEVEL_LOW = 3 };

The method DiagnosticsAPI IsTraceEnabled tests if the specified level of tracing is enabled in the application for the Enterprise Vault tracing utility (Dtrace). When sending a trace message to Dtace, the DiagnosticsAPI Trace method uses this enumeration to set the trace level to be associated with the message. See “IDiagnosticsAPI : IsTraceEnabled” on page 325. See “IDiagnosticsAPI : Trace” on page 326.

EV_STG_API_ARCHIVE_TYPE enumeration Archive type enumeration indicates the type of archive: enum EV_STG_API_ARCHIVE_TYPE { ARCHIVE_TYPE_NOT_SET ARCHIVE_TYPE_SHARED ARCHIVE_TYPE_EXCHANGE_MAILBOX ARCHIVE_TYPE_EXCHANGE_JOURNAL ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER ARCHIVE_TYPE_FILE_SYSTEM ARCHIVE_TYPE_SHAREPOINT ARCHIVE_TYPE_DOMINO_JOURNAL ARCHIVE_TYPE_DOMINO_MAILBOX };

= = = = = = = = =

0x00000000, 0x00000001, 0x00000002, 0x00000004, 0x00000008, 0x00000010, 0x00000020, 0x00000040, 0x00000080

The properties, IArchives::ArchiveTypes and IArchive3::Type, select archives based on the type of archive specified by this enumeration. See “IArchives :: ArchiveTypes” on page 127. See “IArchive3 :: Type” on page 162.

EV_STG_API_AUTHENTICATE_USING enumeration Storage authentication enumeration indicates the authentication mode to use when authenticating to Enterprise Vault.

77

78

Content Management API Enumerations

enum EV_STG_API_AUTHENTICATE_USING { AUTHENTICATE_USING_DCOM_SECURITY = 0, AUTHENTICATE_USING_AUTHSERVER = 1 AUTHENTICATE_USING_MOST_APPROPRIATE_MODE = 2 };

AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default value. This value means that DCOM will be used. Authentication using the Enterprise Vault authentication server can only be used by applications installed on a configured Enterprise Vault server, and should only be used on advice from Symantec Support. See “IContentManagementAPI :: AuthenticationMode” on page 99.

EV_STG_API_CAN_DELETE enumeration Can delete enumeration indicates whether or not the item can be deleted. enum EV_STG_API_CAN_DELETE { DELETE_ALLOWED = 0, DELETE_ACCESS_DENIED = 1, DELETE_RETCAT_ONHOLD = 2, DELETE_ITEM_ONHOLD = 4, DELETE_ITEM_COMPLIANCE = 8 };

The Item CanBeDeleted method returns the current value for an item. Values that indicate that the item cannot be deleted have the following meanings: DELETE_ACCESS_DENIED

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

DELETE_RETCAT_ONHOLD

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

DELETE_ITEM_ONHOLD

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

DELETE_ITEM_COMPLIANCE

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

See “IItem :: CanBeDeleted” on page 200.

Content Management API Enumerations

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

The property, Archive ConvertedContent, is used to set or retrieve the enumeration value. See “IArchive :: ConvertedContent” on page 138.

EV_STG_API_CP_SETBY enumeration Compliance set by enumeration is for use with compliance devices only. It indicates where the compliance retention period is set: enum EV_STG_API_CP_SETBY { SETBY_NOTSET = 0, SETBY_SELF = 1, SETBY_RETCAT = 2 };

The property, ComplianceData SetBy, uses this enumeration value to define where the compliance retention period is set: SETBY_NOTSET

A compliance retention period is not set.

SETBY_SELF

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

SETBY_RETCAT

(Default) The compliance retention period is set by the associated Enterprise Vault retention category.

See “IArchiveMetaData :: ComplianceData” on page 233.

79

80

Content Management API Enumerations

See “IComplianceData :: SetBy” on page 284.

EV_STG_API_CP_UNITS enumeration Compliance units enumeration indicates the units used in specifying the compliance period: enum EV_STG_API_CP_UNITS { CP_UNITS_DAYS =0, CP_UNITS_WEEKS = 1, CP_UNITS_MONTHS = 2, CP_UNITS_YEARS = 3, CP_UNITS_DEFAULT = 4, CP_UNITS_NONE = 5 };

CP_UNITS_NONE is actually the default value, not CP_UNITS_DEFAULT. See “IComplianceData :: Units” on page 282.

EV_STG_API_DELETION_REASON enumeration Deletion reason enumeration indicates why an item has been deleted from the archive. enum EV_STG_API_DELETION_REASON { DELETION_REASON_NONE = 0, DELETION_REASON_USER = 1, DELETION_REASON_EXPIRY = 2, DELETION_REASON_SYSTEM = 3 DELETION_REASON_UNKNOWN = 2147483647 }

If an item no longer exists in the archive, the Item DeletionReason property can be used to find out why the item was deleted. the Item DeletionReason property uses the EV_STG_API_DELETION_REASON enumeration. The enumeration values have the following meanings: DELETION_REASON_NONE

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

DELETION_REASON_USER

Indicates that the item was deleted by a user.

Content Management API Enumerations

DELETION_REASON_EXPIRY

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

DELETION_REASON_SYSTEM

Indicates that the item was deleted by the Enterprise Vault system. This value may be returned, for example, when the archive has been deleted, or if Enterprise Vault could not complete the archiving process because the vault store could not be backed up.

DELETION_REASON_UNKNOWN

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

See “IItem2 :: DeletionReason” on page 208.

EV_STG_API_EXPIRE_ITEMS enumeration Expire items enumeration indicates whether expired items should be deleted automatically from the archive: enum EV_STG_API_EXPIRE_ITEMS { DONT_EXPIRE_ITEMS = 0, EXPIRE_ITEMS = 1 };

The property Archive ExpireItems can be used to return the enumeration value for an existing archive, or set the required value for a new archive before Archive Create is called. See “IArchive :: ExpireItems” on page 136.

EV_STG_API_INDEX_LEVEL enumeration Index level enumeration indicates how much of an item is indexed: enum EV_STG_API_INDEX_LEVEL { INDEX_LEVEL_BRIEF = 0, INDEX_LEVEL_MEDIUM = 1, INDEX_LEVEL_FULL = 2, INDEX_LEVEL_DEFAULT = 3 };

The Enterprise Vault Indexing service manages the indexes of archived data to enable users to search for archived items. When users search the archives to

81

82

Content Management API Enumerations

which they have access, the index volume files are searched. The more information that is indexed about an item, the quicker it is to find the item. However, the more information that is indexed about an item, the more disk space is required for the index. Note: INDEX_LEVEL_MEDIUM is only available on servers running Enterprise Vault 9 or earlier. If INDEX_LEVEL_MEDIUM is requested on an Enterprise Vault 10.0 server, then INDEX_LEVEL_FULL is implemented. See “About indexing options” on page 442. FULL indexing is required for phrase searches of the content property (IndexPropCONT). The property, IArchive::IndexLevel, is used to determine the level of detail stored in the archive's index. See “IArchive :: IndexLevel” on page 142.

EV_STG_API_INDEX_URGENCY enumeration Index urgency enumeration indicates whether to index items as they are stored: enum EV_STG_API_INDEX_URGENCY { INDEX_ITEMS_IMMEDIATELY = 0, INDEX_ITEMS_DEFER_INDEFINITELY = 1 };

Deferring indexing may be useful if you want to store a very large number of items quickly. If INDEX_ITEMS_DEFER_INDEFINITELY is set, the items will not be indexed until the value has been reset to IMMEDIATELY. Thereafter, the next time the Indexing Service runs, it will process the indexing backlog. The Archive IndexUrgency property is used to access index urgency information. See “IArchive :: IndexUrgency” on page 140.

EV_STG_API_ITEM_COPYOPTIONS enumeration The Item CopyOptions property uses this enumeration to identify the source item property values that are to be copied to the destination item when an archived item is moved or copied to a different location.

Content Management API Enumerations

enum EV_STG_API_ITEM_COPYOPTIONS { ITEM_COPYOPTIONS_UNSPECIFIED = 0x00000000, ITEM_COPYOPTIONS_ARCHIVEMETADATA = 0x00000002, ITEM_COPYOPTIONS_MERGE_INDEXMETADATA = 0x00000004 } ;

The default value is ITEM_COPYOPTIONS_ARCHIVEMETADATA. ■

ITEM_COPYOPTIONS_ARCHIVEMETADATA (Default value) If this is set, then the values of the the following ArchiveMetaData properties on the source item will be copied to the equivalent properties on the destination item, unless explicitly provided as part of the CopyTo or MoveTo method call: SimpleIndexMetadata ArchivedDate RetentionCategory CurrentLocation CurrentFolder CustomIdentifier CustomQualifier CustomProperties

■

ITEM_COPYOPTIONS_MERGE_INDEXMETADATA If this is set, then the resulting destination item will include the custom index metadata properties on the source item and also any additional custom index metadata properties that were added to the destination item before the copy or move operation was performed.

See “IItem :: CopyOptions” on page 187.

EV_STG_API_ITEM_DETAIL enumeration Item detail enumeration indicates the data to populate for an Item.Get request: enum EV_STG_API_ITEM_DETAIL { DETAIL_LEVEL_ITEM_PROPERTIES = 1, DETAIL_LEVEL_ITEM_CONTENT = 2, DETAIL_LEVEL_ARCHIVE_METADATA = 4, DETAIL_LEVEL_COMPLIANCE_DATA = 8, DETAIL_LEVEL_HOLD_DATA = 16, DETAIL_LEVEL_CUSTOM_INDEX_METADATA = 32, DETAIL_LEVEL_SYSTEM_INDEXDATA = 64, DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA = 128

83

84

Content Management API Enumerations

DETAIL_LEVEL_SENDER_RECIPIENT_INDEXDATA = 256 };

The following table lists the properties that are populated for the different item detail levels. Table 4-2

Properties populated for EV_STG_API_ITEM_DETAIL enumeration values

Enumeration value

Properties populated

DETAIL_LEVEL_ITEM_PROPERTIES

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

DETAIL_LEVEL_ITEM_CONTENT

IContent.Data

DETAIL_LEVEL__ARCHIVE_METADATA

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

DETAIL_LEVEL__COMPLIANCE_DATA

IArchiveMetadata.ComplianceDevice IArchiveMetadata.RetentionExpires

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.Holds See “Holds object” on page 285.

DETAIL_LEVEL__CUSTOM_INDEX_METADATA

IArchiveMetadata.IndexData — custom index properties only. (System properties are not included). See “Adding custom index metadata” on page 72.

DETAIL_LEVEL__SYSTEM_INDEXDATA

IArchiveMetadata.IndexData — system properties only, excluding the "menv" and "sere" properties. See “System properties” on page 596.

DETAIL_LEVEL__MESSAGE_ENVELOPE_INDEXDATA

IArchiveMetadata.IndexData — "menv" system property only. See “System properties” on page 596.

DETAIL_LEVEL__SENDER_RECIPIENT_INDEXDATA

IArchiveMetadata.IndexData — "sere" system property only. See “System properties” on page 596.

See “IItem :: Get” on page 194. See “System properties” on page 596.

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

85

86

Content Management API Enumerations

PERMISSIONS_READ_WRITE = PERMISSIONS_READ|PERMISSIONS_WRITE, PERMISSIONS_READ_WRITE_DELETE = PERMISSIONS_READ |PERMISSIONS_WRITE |PERMISSIONS_DELETE, PERMISSIONS_WRITE_DELETE = PERMISSIONS_WRITE |PERMISSIONS_DELETE, PERMISSIONS_READ_DELETE = PERMISSIONS_READ |PERMISSIONS_DELETE, PERMISSIONS_FOLDER_READ_WRITE= PERMISSIONS_FOLDER_READ |PERMISSIONS_FOLDER_WRITE, PERMISSIONS_FOLDER_READ_WRITE_DELETE = PERMISSIONSFOLDER__READ |PERMISSIONS_FOLDER_WRITE |PERMISSIONS_FOLDER_DELETE, PERMISSIONS_FOLDER_WRITE_DELETE = PERMISSIONS_FOLDER__WRITE |PERMISSIONS_FOLDER_DELETE, PERMISSIONS_FOLDER_READ_DELETE = PERMISSIONS_FOLDER_READ |PERMISSIONS_FOLDER_DELETE, };

The Archives Permissions property uses this enumeration to select archives based on the archive access permissions of the caller. The Archive SecurityDescriptor property represents the manually set permissions on an archive, which are displayed on the Permissions tab of the archive properties dialog in the Enterprise Vault Administration Console. EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security descriptor permissions for an archive. See “IArchives :: Permissions” on page 126. See “IArchive3 :: SecurityDescriptor” on page 157.

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

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, and whether it can be accessed. See “IVaultStore :: Status” on page 115. See “IArchive2 :: Status” on page 154.

ContentManagementAPI object This object provides top-level access (via the appropriate interfaces) to archives, items and holds, and enables you to set and retrieve the Directory DNS Alias and Authentication mode. This object implements the following interfaces: ■

IContentManagementAPI

■

IContentManagementAPI2

■

IContentManagementAPI3

■

IContentManagementAPI4 (default)

The IContentManagementAPI interface defines methods and properties enabling access to archives, vault stores and items. This interface inherits the methods of the IDispatch interface. The IContentManagementAPI2 interface provides additional properties for accessing Enterprise Vault Directory information about vault stores and archives. The IContentManagementAPI3 interface provides a property for enumerating items stored in an archive, and a method to enable applications written in Visual Basic script to access the IContentManagementAPI3 interface. The IContentManagementAPI4 interface provides calling applications with extended error information if an error is encountered when using the Content Management API methods.

Syntax interface interface interface interface

IContentManagementAPI : IDispatch IContentManagementAPI2 : IContentManagementAPI IContentManagementAPI3 : IContentManagementAPI2 IContentManagementAPI4 : IContentManagementAPI3

87

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.

Item

Read only

Returns an empty instance of an Item object.

Holds

Read only

Returns an empty instance of a Holds object.

Hold

Read only

Returns an empty instance of a Hold object.

DirectoryDNSAlias

Read/Write

Identifies an Enterprise Vault server running an Enterprise Vault Directory Service.

AuthenticationMode

Read/Write

Gets or sets the authentication mode.

Table 4-4

IContentManagementAPI2 properties

Property

Read/Write

Description

VaultStores

Read only

Returns an empty instance of a VaultStores object.

VaultStore

Read only

Returns an empty instance of a VaultStore object.

Archives

Read only

Returns an empty instance of an Archives object.

Table 4-5

IContentManagementAPI3 property

Property

Read/Write

Description

Items

Read only

Returns an empty instance of an Items object.

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, depending on the Interface Indentifier string (IID) passed to it. This enables applications written in Visual Basic script to access the IContentManagementAPI3 interface.

Table 4-7

IContentManagementAPI4 method

Method

Read

Description

LastError

Read

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

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

Requirements ■

MSXML 6.0 or later is required on the computer where you install the Enterprise Vault API runtime.

CLSID

E4BE20A4-9EF1-4B05-9117-AF43EAB4B295

89

90

Content Management API ContentManagementAPI object

Prog ID

EnterpriseVault.ContentManagementAPI

Type Library

EVContentManagementAPILib

DLL

EVContentManagementAPI.dll

.NET Primary Interop Assembly (PIA)

KVS.EnterpriseVault.Interop.EVContentManagementAPI.dll

.NET PIA namespace

KVS.EnterpriseVault.Interop

Version information ■

The property, IContentManagementAPI::AuthenticationMode requires Enterprise Vault 7.0 or later.

■

The IContentManagementAPI2 interface requires Enterprise Vault 2007 or later.

■

The IContentManagementAPI3 interface requires Enterprise Vault 8.0 or later.

■

The IContentManagementAPI4 interface requires Enterprise Vault 8.0 SP2 or later.

Examples [C++] #import "c:\program files\Enterprise Vault\ EVContentManagementAPI.dll" no_namespace, raw_interfaces_only

class SomeClass { IContentManagementAPI4* m_pCmAPI = NULL; public: void SomeClass() { CLSID clsid; CLSIDFromProgID(L"EnterpriseVault.ContentManagmentAPI", &clsid); CoCreateInstance(clsid, NUKK, CLSCTX_ALL, __uuidof

Content Management API IContentManagementAPI :: Archive

(IContentManagementAPI), reinterpret_cast (&m_pCmAPI)); //do something else } [C#] using KVS.EnterpriseVault.Interop;

public class SomeClass { IContentManagementAPI4 cmAPI = new ContentManagementClass(); //rest of class }

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

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

Parameters [out,retval] IArchive** pVal

A pointer, when successful, to the location of the IArchive pointer to the newly created archive object. This parameter is set to NULL if an error occurs.

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

91

92

Content Management API IContentManagementAPI :: Archive

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Examples In the following examples it is assumed a reference to IContentManagmentAPI, m_pCmAPI (C++) or cmAPI (C#) has already been obtained. [C++] IArchive* pArchive = NULL: m_pCmAPI->get_Archive(&pArchive); CComBSTR bstrID(L"1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"); CComBSTR bstrVaultStoreId(L"16D002240AEDFAC45A44E7FBE88FDC7721 210000EVSite"); pArchive->put_Id(bstrID); pArchive->put_VaultStoreId(bstrVaultStoreId); pArchive->Get(); //Do something pArchive->Release(); pArchive = NULL; [C#] IArchive archive = cmAPI.Archive; archive.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; archive.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; archive.Get(); //do something System.Runtime.InteropServices.FinalReleaseComObject(archive); archive = null;

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, such as creating an item and adding it to an archive, fetching data, getting item properties, deleting items from an archive, copying or moving items. This property is read only.

Syntax HRESULT Item([out, retval] IItem** pVal)

Parameters [out, retval] IItem** pVal

A pointer, when successful, to the location of the IItem pointer to the newly created item object. This parameter is set to NULL if an error occurs.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Examples [C++] IItem* pItem = NULL: m_pCmAPI->get_Item(&pItem); CComBSTR bstrID(L"68bd9b6a-6355-4468-b647-0ec33ade6340"); //note transaction id used CComBSTR bstrArchId(L"1C9EFA88998592944ADB634ACC0D7410 D1110000EVSite"); pItem->put_Id(bstrID);

94

Content Management API IContentManagementAPI :: Holds

pItem->put_ArchiveId(bstrArchId);

//get item properties pItem->Get(DETAIL_LEVEL_ITEM_PROPERTIES); //Do something with the properties

pItem->Release(); pItem = NULL; [C#] IItem itm = cmAPI.Item; itm.Id = "68bd9b6a-6355-4468-b647-0ec33ade6340"; itm.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; //get item properties itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES); System.Runtime.InteropServices.Marshal.FinalReleaseComObject(item); item = null;

See also ■

See “Content object” on page 212.

■

See “ArchiveMetaData object” on page 225.

■

See “SimpleIndexMetadata object” on page 256.

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

Content Management API IContentManagementAPI :: Holds

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

Parameters [out, retval] IHolds** pVal

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

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Examples [C++] IHolds* pHolds = NULL: m_pCmAPI->get_Holds(&pHolds); //Do something pHolds->Release(); pHolds = NULL; [C#] IHolds holds = cmAPI.Holds; //do something System.Runtime.InteropServices.FinalReleaseComObject(holds); holds = null;

See also ■

See “Holds object” on page 285.

95

96

Content Management API IContentManagementAPI :: Hold

■

See “Hold object” on page 300.

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

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

Parameters [out, retval] IHold** pVal

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

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Examples [C++] IHolds* pHolds = NULL: m_pCmAPI->get_Holds(&pHolds); IHold* pHold = NULL; m_pCmAPI->get_Hold(&pHold);

Content Management API IContentManagementAPI :: DirectoryDNSAlias

//Set properties pHolds->Add(pHold); pHold->Release(); pHold = NULL; pHolds->Release(); pHolds = NULL; [C#] IHolds holds = cmAPI.Holds; IHold hold = cmAPI.Hold; //add some properties holds.Add(hold); System.Runtime.InteropServices.FinalReleaseComObject(holds); holds = null; System.Runtime.InteropServices.FinalReleaseComObject(hold); hold = null;

See also ■

See “Holds object” on page 285.

■

See “Hold object” on page 300.

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

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

97

98

Content Management API IContentManagementAPI :: DirectoryDNSAlias

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that, on return, will contain the current value.

[in] BSTR newVal

The new value can be any one of the following: DNS alias of a computer hosting an Enterprise Vault Directory Service. ■ IP address of a computer hosting an Enterprise Vault Directory Service. ■ Id of the Enterprise Vault Site. ■

■

Id of any archive in the Site.

■

Id of any vault store in the Site.

Remarks The ID of an Enterprise Vault site can be found in the following registry entry on an Enterprise Vault server: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \SiteID

The ID of an archive can be found in the Enterprise Vault Administration Console, in the properties dialog for an archive. Similarly, the ID of a vault store can be found in the Administration Console, in the properties dialog for a vault store.

Return value S_OK

Success.

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

Content Management API IContentManagementAPI :: AuthenticationMode

[C#] [out] string dns = cmAPI.DirectoryDNSAlias; [in] cmAPI.DirectoryDNSAlias = dns;

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

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

Parameters [out, retval]EV_STG_API_AUTHENTICATE_USING* pVal

Pointer to an EV_STG_API_ AUTHENTICATE _USING object which will return the current authentication mode.

[in]EV_STG_API_AUTHENTICATE_USING newVal

New value for the authentication mode.

Remarks The EV_STG_API_AUTHENTICATE_USING enumerator defines the authentication mode to use.

99

100

Content Management API IContentManagementAPI2 :: VaultStores

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Examples [C++] m_pCmAPI->put_AuthenticationMode(AUTHENTICATE_USING_DCOM_SECURITY); [C#] cmAPI.AuthenticationMode = EV_STG_API_AUTHENTICATE_USING.AUTHENTICATE_USING_DCOM_SECURITY;

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

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

Content Management API IContentManagementAPI2 :: VaultStore

Parameters [out, retval] IUnknown** pVal

Reference to an empty VaultStores object.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL

Examples [C++] IVaultStores pVaultStores = NULL; m_pCmAPI->get_VaultStores(&pVaultStores); CComBSTR bstrComputer(L"EVSERVER1"); pVaultStores->put_Computer(bstrComputer); pVaultStores->Get(); [C#] IVaultStores vaultStores = cmAPI.VaultStores; vaultStores.Computer = "EVSERVER1"; vaultStores.Get();

See also ■

See “VaultStores object” on page 107.

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

101

102

Content Management API IContentManagementAPI2 :: VaultStore

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

Parameters [out, retval] IUnknown** pVal

Reference to an empty VaultStore object.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL

Examples [C++] CComPtr spVaultStore; CComPtr spUnk; m_pCmAPI->get_VaultStore(&pUnk); spUnk->QueryInterface(&spVaultStore); CComBSTR bstrID(L"16D002240AEDFAC45A44E7FBE88FDC772121 0000EVSite"); spVaultStore->put_Id(bstrID); spVaultstore->Get(); [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.ID = "16D002240AEDFAC45A44E7FBE88FDC7721210000 EVSite"; vaultStore.Get();

See also ■

See “VaultStore object” on page 110.

Content Management API IContentManagementAPI2 :: Archives

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

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

Parameters [out, retval] IUnknown** pVal

An instance of an Archives object.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL

Example [C++] CComPtr spArchives; CComPtr spUnk; m_pCmAPI->get_Archives(&spUnk); spUnk->QueryInterface(&spArchives); CComBSTR bstrVaultStore(L"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"); spArchives->put_VaultStore(bstrVaultStore); spArchives->put_ArchiveTypes(ARCHIVE_TYPE_EXCHANGE_MAILBOX);

See also ■

See “Archives object” on page 119.

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

103

104

Content Management API IContentManagementAPI3 :: IDispatchQueryInterface

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

Parameters [out, retval] IUnknown** pVal

Reference to an empty Items object.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL

Example [C++] // Get empty items collection for populating CComPtr spCMAPI; spCMAPI.CreateInstance(CComBSTR(L"EnterpriseVault.ContentManagement API")); CComPtr spUnk; // Get an Items object for enumeration spCMapi->get_Items(&spUnk); CComQIPtr spItems(spUnk);

See also ■

See “Items object” on page 164.

IContentManagementAPI3 :: IDispatchQueryInterface This method enables calling applications written in Visual Basic Script to access the properties of the following interfaces:

Content Management API IContentManagementAPI3 :: IDispatchQueryInterface

■

IArchive3

■

IArchiveMetaData2

■

IItem2

IArchive3 and IArchiveMetaData2 were introduced at Enterprise Vault 8.0. IItem2 was introduced at Enterprise Vault 8.0 SP3.

Syntax HRESULT IDispatchQueryInterface ([in] IDispatch* pUnkObj, [in] BSTR interfaceId, [out, retval] IDispatch** ppUnkRetVal);

Parameters [in] IDispatch* pUnkObj

IDispatch interface pointer associated with the object being queried.

[in] BSTR interfaceId

Interface Identifier (IID) string associated with the interface being queried.

[out, retval] IDispatch** ppUnkRetVal

Pointer for returning the queried interface object.

Remarks The pointer for returning the queried interface object returns NULL, and an error is reported, if the interface is not supported. When running scripts on a 64-bit operating system, use the 32-bit version of command prompt, C:\Windows\SysWOW64\cmd.exe.

Return value S_OK

Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

105

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, in order to access the IArchiveMetaData2::SequenceNum property. dim cmAPI, item, SeqNo, IAMD2 set cmAPI = CreateObject("EnterpriseVault.ContentManagementAPI") set item = ContentManagementAPI.Item set IAMD2 = cmAPI.IDispatchQueryInterface(item.ArchiveMetaData, "{5C6882BD-24BE-4C32-87EF-C3701D949BAA}") if (IAMD2 is nothing) then MsgBox "ArchiveMetaData2 API Object create failed!" end if SeqNo = IAMD2.SequenceNum

See also ■

See “Archive object” on page 128.

■

See “ArchiveMetaData object” on page 225.

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

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

Parameters [out,retval] IUnknown** pVal

A reference to an ExtendedErrorInfo object.

Remarks The ExtendedErrorInfo object provides error details for the last call to a Content Management API method.

Content Management API VaultStores object

It is important to follow recommended best practice, and avoid sharing IContentManagementAPI interface objects across threads, as this could cause error information from a call on another thread to be returned. See “Programming notes” on page 56.

Return value S_OK

Success

See also ■

See “ExtendedErrorInfo object” on page 316.

VaultStores object This object implements the following interface: ■

IVaultStores

The IVaultStores interface inherits the properties and methods of the ICollectionBase interface. The IVaultStores interface enables applications to enumerate the vault stores configured in an Enterprise Vault Site.

Syntax interface IVaultStores : ICollectionBase

Member summary Table 4-8

IVaultstores properties

Property

Read/Write

Description

Computer

Read/Write

Identity of an Enterprise Vault server running a Directory Service.

Details of the properties and methods of the ICollectionBase interface are provided in later sections of this guide. See Table 4-9 on page 108. See Table 4-10 on page 108.

107

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.

_NewEnum

Read only

Instance of the standard COM enumerator for the collection.

Item

Read only

Instance of the vault store at the zero-based index into the collection.

Maximum

Read/Write

Maximum number of vault stores in the collection.

More

Read only

Whether or not there were more vault stores than Maximum.

Table 4-10

ICollectionBase methods

Method

Description

Get

Populate the collection.

Clear

Clear the current collection.

Reset

Reset the object back to the initial state.

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

Version information ■

This interface is available from Enterprise Vault 2007.

Example This example code lists all vault stores based on a Computer DNS name. [C#] IContentManagementAPI3 cmAPI = (IContentManagementAPI3)

Content Management API IVaultStores :: Computer

new ContentManagementAPI(); IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores; // Populate collection from EV1 vaultStores.Computer = "EV1.Acme.com"; vaultStores.Get(); // Process each Vault Store foreach(IVaultStore vaultStore in vaultStores) { ProcessIt(vaultStore.Id, vaultStore.Name); }

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

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

Parameters [in] BSTR pVal

The DNS name of an Enterprise Vault server, or the Id of an Enterprise Vault entity, such as site or vault store.

[out, retval] BSTR* pVal

A pointer to a string that will hold the returned value.

Remarks This property can be set with any identifier that Enterprise Vault can use to identify an Enterprise Vault server running a Directory Service, for example: ■

DNS name

■

IP address

■

The Id of an Enterprise Vault entity, for example: ■

Enterprise Vault Site Id

■

Vault store Id

■

Archive Id

109

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 an archive. Similarly, the Id of a vault store can be found in the Administration Console, in the properties dialog for a vault store. If the Computer property is left empty, its value defaults to the current value of the DirectoryDNSAlias property of the parent IContentManagementAPI instance.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL

Example [C#] IContentManagementAPI3 cmAPI = (IContentManagementAPI3) new ContentManagementAPI(); IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores; // Populate collection from EV1 vaultStores.Computer = "EV1.Acme.com"; vaultStores.Get(); // Process each Vault Store foreach(IVaultStore vaultStore in vaultStores) { ProcessIt(vaultStore.Id, vaultStore.Name); }

VaultStore object This object implements the following interface:

Content Management API VaultStore object

■

IVaultStore

The IVaultStore interface enables external applications to get details of a vault store.

Syntax interface IVaultStore : IDispatch

Member summary Table 4-11

IVaultstore properties

Property

Read/Write

Description

Id

Read/Write

Vault store Id.

Name

Read only

Vault store name.

Description

Read only

Vault store description.

Status

Read only

Status of vault store.

ArchiveCount

Read only

Number of archives in the vault store.

DirectoryDNSAlias Read only

Table 4-12

Identifies an Enterprise Vault server running an Enterprise Vault Directory Service.

IVaultStore methods

Method

Description

Get

Get the details of the selected vault store.

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

Version information ■

This interface is available from Enterprise Vault 2007.

111

112

Content Management API IVaultStore :: Id

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties string name = vaultStore.Name; string description = vaultsStore.Description; string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.ArchiveCount;

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

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

Parameters [in] BSTR pVal

Id of the required vault store.

[out, retval] BSTR* pVal

String that will contain the Id of the vault store.

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

Return value S_OK

Success.

Content Management API IVaultStore :: Name

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties string name = vaultStore.Name; string description = vaultsStore.Description; string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.ArchiveCount;

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

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

Parameter [out, retval] BSTR* pVal

Name of the vault store.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

113

114

Content Management API IVaultStore :: Description

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties string name = vaultStore.Name; string description = vaultsStore.Description; string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.ArchiveCount;

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

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

Parameter [out, retval] BSTR* pVal

Vault store description.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties

Content Management API IVaultStore :: Status

string name = vaultStore.Name; string description = vaultsStore.Description; string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.Count;

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

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

Parameter [out, retval] EV_STG_API_STATUS* pVal

EV_STG_API_STATUS enumerated value.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties string name = vaultStore.Name; string description = vaultsStore.Description;

115

116

Content Management API IVaultStore :: ArchiveCount

string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.ArchiveCount;

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

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

Parameter [out, retval] long* pVal

Number of archives currently in the vault store.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory service is not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Content Management API IVaultStore :: DirectoryDNSAlias

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties string name = vaultStore.Name; string description = vaultsStore.Description; string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.ArchiveCount;

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

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

Parameter [out, retval] BSTR* pVal

DNS alias for the Enterprise Vault Site.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

117

118

Content Management API IVaultStore :: Get

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties string name = vaultStore.Name; string description = vaultsStore.Description; string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.ArchiveCount;

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

Syntax HRESULT Get(void);

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The Id property is empty.

CONTENTMANAGEMENTAPI_E_NOT_FOUND

The vault store does not exist.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory service is not running.

Content Management API Archives object

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Example [C#] IVaultStore vaultStore = cmAPI.VaultStore; vaultStore.Id = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; vaultStore.Get(); //now get vault store properties string name = vaultStore.Name; string description = vaultsStore.Description; string dnsAlias = vaultStore.DirectoryDNSAlias; EV_STG_API_STATUS evStatus = vaultStore.Status; long count = vaultStore.ArchiveCount;

Archives object This object implements the following interface: ■

IArchives

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

Syntax interface IArchives : ICollectionBase

119

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.

VaultStoreId

Read/Write

Id of the vault store containing the required archive or archives.

ArchiveName

Read/Write

Name, or part of the name, of the required archive or archives.

Permissions

Read/Write

Caller's access permissions on the required archive or archives.

ArchiveTypes

Read/Write

Types of archives required.

The properties and methods of the ICollectionBase interface are described in later sections. See Table 4-14 on page 120. See Table 4-15 on page 121. 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.

Item

Read only

Instance of the archive at the zero-based index into the collection.

Maximum

Read/Write

Maximum number of archives in the collection.

More

Read only

Indicates whether there are more archives available than the maximum allowed in the collection.

Content Management API Archives object

Table 4-15

ICollectionBase methods

Method

Description

Get

Populate the collection.

Clear

Clear the current collection.

Reset

Reset the object back to the initial state.

Remarks Use the ICollectionBase :: Get method of this interface to obtain a collection of Archive objects, and automatically populate the properties of each Archive object. The properties of the IArchives interface enable you to select which archives you want returned. The ICollectionBase :: Get method supports archive selection using combinations of properties, subject to the following rules: ■

■

If you set Computer, you can also set the one of the following properties or combinations of properties: ■

ArchiveName

■

ArchiveName and ArchiveType

■

Permissions

■

Permissions and ArchiveType

■

ArchiveType

If you set VaultStoreId, the only other property that you can set is ArchiveType.

No other combinations of properties are supported.

Version information ■

This interface requires Enterprise Vault 2007 or later.

Example This example lists all Exchange Server mailbox archives that can be searched by the caller, based on the DNS Alias for an Enterprise Vault Site. [C#] IArchives archives = (IArchives)cmAPI.Archives;

121

122

Content Management API IArchives :: Computer

See also ■

See “Enumerating vault stores, archives and items” on page 70.

■

See “ICollectionBase : IDispatch” on page 308.

■

See “Archive object” on page 128.

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

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

Parameters [in] BSTR pVal

The DNS name of an Enterprise Vault server, or the Id of an Enterprise Vault entity, such as site or vault store.

[out, retval] BSTR* pVal

A pointer to a string that will hold the returned value.

Remarks This property can be set with any identifier that Enterprise Vault can use to identify an Enterprise Vault server running a Directory Service, for example: ■

DNS name

■

IP address

■

The Id of an Enterprise Vault entity in the Directory, for example: ■

Enterprise Vault Site Id

■

Vault store Id

■

Archive Id

The Id of an Enterprise Vault Site can be found in the following registry entry on an Enterprise Vault server:

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, in the properties dialog for an archive. Similarly, the Id of a vault store can be found in the Administration Console, in the properties dialog for a vault store. If the Computer property is left empty, its value defaults to the current value of the DirectoryDNSAlias property of the parent IContentManagementAPI instance.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example This example gets all the archives that the user has permission to search. [C#] IArchives archives = (IArchives)cmAPI.Archives; archives.Computer = "EV1.acme.com"; archives.Permissions = EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH; archives.Get();

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

123

124

Content Management API IArchives :: ArchiveName

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

Parameters [in] BSTR pVal

Id of the required vault store.

[out, retval] BSTR* pVal

String that will contain the Id of the vault store.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL or pVal is not a valid vault store identity.

Example This example gets all Exchange Server mailbox archives in a particular vault store. [C#] IArchives archs = (IArchives)cmAPI.Archives; archs.VaulStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; archs.ArchiveTypes = EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_EXCHANGE_MAILBOX; archs.Get();

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

Content Management API IArchives :: ArchiveName

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

Parameters [in] BSTR pVal

Name or partial name of required archive or archives.

[out, retval] BSTR* pVal

Pointer to a string that will contain the archive names.

Remarks Multiple archives can be selected by use of common wildcard syntax. The following wildcard features are supported: ■

* to match none, one or any number of characters.

■

% to match any single character.

■

[] matches any single character within the specified range or set (case insensitive). For example

■

■

■

[abdf] to match any of the set of characters a,b,d, or f.

■

[a-f] to match any of the range of characters a,b,c,d,e, or f.

[^] to match any single character not in the specified range or set (case insensitive). For example ■

[^abdf] to match any character not in the set of characters a, b,d, or f.

■

[^a-f] to match any character not in the range of characters a,b,c,d,e, or f.

\ escapes *, %, or [ to enable matching on those characters. For example, 50\% is used to match with 50%.

The returned collection is ordered by archive name.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

125

126

Content Management API IArchives :: Permissions

Example This example retrieves all archives with a name ending in ‘Smith’. [C#] IArchives archs = cmAPI.Archives; archs.Computer = "SERVER1"; archs.ArchiveName = "*Smith"; archs.Get();

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

Syntax HRESULT Permissions([in] EV_STG_API_PERMISSIONS_TYPE pVal); HRESULT Permissions([out, retval] EV_STG_API_PERMISSIONS_TYPE* pVal);

Parameters [in] EV_STG_API_PERMISSIONS_TYPE pVal

New EV_STG_API _PERMISSIONS_TYPE value.

[out, retval] EV_STG_API_PERMISSIONS_TYPE* pVal

Caller's archive access permissions.

Remarks EV_STG_API_PERMISSIONS_TYPE is an enumerated type that indicates the required archive permissions. See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 85. The permissions checks are based on the current Windows identity of the caller. If the caller is currently impersonating, then the impersonation identity is used. Currently there is no support for the Lotus Domino authentication model.

Content Management API IArchives :: ArchiveTypes

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example [C#] IArchives archives = (IArchives)cmAPI.Archives; archives.Computer = "EV1.acme.com"; archives.Permissions = EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH; archives.Get();

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

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

Parameters [in] LONG pVal

One or more values of EV_STG_API_ARCHIVE_TYPE.

[out, retval] LONG* pVal

One or more values of EV_STG_API_ARCHIVE_TYPE.

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

127

128

Content Management API Archive object

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example [C#] IArchives archives = (IArchives)cmAPI.Archives; archives.ArchiveTypes = (int)EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_EXCHANGE_MAILBOX; archives.Permissions = (int)EV_STG_API_PERMISSIONS_TYPE.PERMISSION_SEARCH; archives.Get();

Archive object This object implements the following interfaces: ■

IArchive IID is {48092C71-5618-4EB5-9060-01030C191450}

■

IArchive2 IID is {B85C5178-0B9D-4987-8DC5-92F77B33879E}

■

IArchive3 IID is {9E2C0ACF-4CB5-4FB3-A9AB-499BB9EE959C}

These interfaces enable the creation and examination of archives in a vault store. IArchive2 provides additional properties to enable querying the type and status of an archive. IArchive3 provides additional properties to enable setting and querying the access security assigned to an archive.

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

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.

Id

Read/Write

Archive ID of the archive.

Name

Read/Write

Name of the archive.

Description

Read/Write

Provides description of the archive.

ExpireItems

Read/Write

Enables automatic storage expiry for archive.

ConvertedContent

Read/Write

Controls whether converted content is stored with item or generated on demand.

IndexLevel

Read/Write

Sets level of indexing.

IndexUrgency

Read/Write

Control whether items are indexed on archiving.

Size

Read only

Size of the archive. (This is not the original item size)

SecurityDescriptor

Write only

Security permissions for the archive, specified as a variant byte array containing a SECURITY_DESCRIPTOR structure.

ComplianceDevice

Read only

Indicates whether the archive resides on a device capable of setting compliance periods.

ItemCount

Read only

Number of items in the archive.

Table 4-17

IArchive2 properties

Property

Read/Write

Description

Type

Read only

The type of the archive.

Status

Read only

Status of the storage where the archive is located, that is, whether it can be accessed.

129

130

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.

Full

Read only

Whether the archive is full.

DirectoryDNSAlias

Read only

Directory DNS Alias of the hosting the archive.

Table 4-18

IArchive3 properties

Property

Read/Write

Description

SecurityDescriptor

Read/Write

The security permissions on the archive specified as a variant byte array containing a SECURITY_DESCRIPTOR structure.

SecurityDescriptorString

Read/Write

The security permissions on the archive specified using Security Descriptor String Format as described in MSDN.

Type

Read/Write

The type of the archive.

Table 4-19

IArchive methods

Method

Description

Create

Creates an archive.

Get

Retrieves details of the selected archive.

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

Version information ■

IArchive2 interface requires Enterprise Vault 2007 or later.

■

IArchive3 interface requires Enterprise Vault 8.0 or later.

Content Management API IArchive :: VaultStoreId

131

Example [C#] IArchive arch = cmAPI.Archive arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get();

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

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

Parameters [in] BSTR newVal

Id of the required vault store.

[out,retval] BSTR* pVal

Pointer to a BSTR that contains the Id of the required vault store

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

Incorrect Id format.

Example arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get();

132

Content Management API IArchive :: Id

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

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

Parameters [in] BSTR newVal

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

[out, retval] BSTR* pVal

Pointer to a BSTR that will contain the current value.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, pVal is not a valid archive identity, or the object is already populated.

Examples arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";

Content Management API IArchive :: Name

arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get();

or [out]

Assume an Archives object, ‘archives’, has been populated. foreach (IArchive archive in archives) { SearchArchive(archive.Id); }

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

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

Parameters [in] BSTR newVal

The name of the archive. Maximum length: 256 characters.

[out,retval] BSTR* pVal

Pointer to a BSTR that will contain the name of an archive.

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

133

134

Content Management API IArchive :: Description

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal contains invalid characters, or the object is already populated.

Example [in] arch.Name = "my new archive"; arch.Description = "my new archive description"; arch.ExpireItems = EV_STG_API_EXPIRE_ITEMS. DONT_EXPIRE_ITEMS; arch.ConvertedContent = EV_STG_API_CONVERTED_CONTENT. CONVERTED_CONTENT_STORED; arch.IndexUrgency = EV_STG_API_INDEX_URGENCY. INDEX_ITEMS_IMMEDIATELY; arch.IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL; arch.Create(); [out] arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get(); string

name = arch.Name;

string description = arch.Description; EV_STG_API_EXPIRE_ITEMS evEI = arch.ExpireItems; EV_STG_API_CONVERTED_CONTENT evCC = arch.ConvertedContent; EV_STG_API_INDEX_URGENCY evIU = arch.IndexUrgency; EV_STG_API_INDEX_LEVEL evIL = arch.IndexLevel; ulong size = (ulong) arch.Size; bool complianceDevice = arch.ComplianceDevice; uint itemCount = (uint) arch.ItemCount;

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

Content Management API IArchive :: Description

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

Parameters [in] BSTR newVal

Description of the archive. Max length: 127 characters.

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

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal contains invalid characters, or the object is already populated.

Examples [C++] CComBstr bstr = new CComBSTR(L"archive description"); archive->put_Description(bstr): //do something - create archive //then check name archive->get_ Description (&bstr); //try changing name

135

136

Content Management API IArchive :: ExpireItems

bstr = L"New description"; archive->put_ Description (bstr);

//ERROR

[C#] archive. Description = "archive description"; //do something - create archive //then check name string name = archive. Description; //try changing name archive. Description = "New description";

//ERROR

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

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

Parameters [out, retval] EV_STG_API_EXPIRE_ITEMS* pVal

Pointer to an EV_STG_API _EXPIRE_ITEMS object that will contain the current value.

[in] EV_STG_API_EXPIRE_ITEMS newVal

Sets a new value of ExpireItems.

Remarks The required value must be set prior to calling Create.

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. Any attempt to change this value in an existing archive will result in an error. Do not attempt to retrieve a value for ExpireItems before creating or getting an archive, as an error will occur. No default value is set for this property. EV_STG_API_EXPIRE_ITEMS is an enumeration type that indicates whether expired items should be deleted automatically from the archive. See “EV_STG_API_EXPIRE_ITEMS enumeration” on page 81. It may be necessary to cast this to an integer if using in C#.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal is invalid, or the object is already populated.

Examples [C++] EV_STG_API_EXPIRE_ITEMS ei = DONT_EXPIRE_ITEMS; archive->put_ExpireItems(ei); //do other things and create archive //Now check value archive->get_ExpireItems(&ei); //try changing value archive->put_ExpireItems(EXPIRE_ITEMS);

//ERROR

[C#] EV_STG_API_EXPIRE_ITEMS ei = EV_STG_API_EXPIRE_ITEMS.DONT_EXPIRE_ITEMS; archive.ExpireItems = ei; //do other things and create archive

137

138

Content Management API IArchive :: ConvertedContent

//Now check value ei = archive.ExpireItems; //try changing value archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS; //ERROR

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

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

Parameters [out, retval]EV_STG_API_CONVERTED_CONTENT* pVal

Pointer to an EV_STG_API_ CONVERTED_CONTENT object that will contain the current value.

[in] EV_STG_API_CONVERTED_CONTENT newVal

The new value of ConvertedContent.

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

Content Management API IArchive :: ConvertedContent

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal is invalid, or the object is already populated.

Examples [C++] EV_STG_API_CONVERTED_CONTENT cc = CONVERTED_CONTENT_STORED; archive->put_ConvertedContent(cc);

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

//try and change the value archive.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.CONVERTED_ON_DEMAND; //ERROR

139

140

Content Management API IArchive :: IndexUrgency

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

Syntax HRESULT IndexUrgency([out, retval] EV_STG_API_INDEX_URGENCY* pVal); HRESULT IndexUrgency([in] EV_STG_API_INDEX_URGENCY newVal);

Parameters [out, retval] EV_STG_API_INDEX_URGENCY* pVal

Pointer to an EV_STG_API _INDEX_URGENCY object that will contain the current value

[in] EV_STG_API_INDEX_URGENCY newVal

New value of EV_STG_API_ INDEX_URGENCY

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

Return value S_OK

Success.

Content Management API IArchive :: IndexUrgency

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal is invalid, or the object is already populated.

Examples [C++] EV_STG_API_INDEX_URGENCY iu = INDEX_ITEMS_IMMEDIATELY; ; archive->put_IndexUrgency(iu);

//do more and create archive //Now check value archive->get_ IndexUrgency (&iu); //try and change value archive->put_ IndexUrgency (INDEX_ITEMS_DEFER_INDEFINITELY); //ERROR [C#] EV_STG_API_INDEX_URGENCY iu = EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_IMMEDIATELY; archive.IndexUrgency = iu; //do other things - create archive //check value iu = Archive. IndexUrgency ; //try and change the value archive. IndexUrgency = EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_DEFER_INDEFINITELY; //ERROR

141

142

Content Management API IArchive :: IndexLevel

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

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

Parameters [out, retval] EV_STG_API_INDEX_LEVEL* pVal

Pointer to an EV_STG_API_ INDEX_LEVEL object that will contain the current value.

[in] EV_STG_API_INDEX_LEVEL newVal

New value of EV_STG_API_ INDEX_LEVEL.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal is invalid, or the object is already populated.

Content Management API IArchive :: Size

Examples [C++] EV_STG_API_INDEX_LEVEL il = INDEX_LEVEL_BRIEF; archive->put_IndexLevel(il); //do something and create archive //Now check value archive->get_ IndexLevel (&il); //try and change value archive->put_ IndexLevel (INDEX_LEVEL_FULL); //ERROR [C#] EV_STG_API_INDEX_URGENCY il = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_BRIEF; archive. IndexLevel = il; //do something - create archive //check value il = Archive. IndexLevel;

//try and change the value archive. IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL; //ERROR

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

143

144

Content Management API IArchive :: Size

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

Parameters [out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the size of the archive, expressed in Kbytes. The VT type is a VT_U18.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, or the object has not been populated.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Example arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get(); string name = arch.Name; string description = arch.Description; EV_STG_API_EXPIRE_ITEMS evEI = arch.ExpireItems; EV_STG_API_CONVERTED_CONTENT evCC = arch.ConvertedContent; EV_STG_API_INDEX_URGENCY evIU = arch.IndexUrgency; EV_STG_API_INDEX_LEVEL evIL = arch.IndexLevel; ulong size = (ulong) arch.Size;

Content Management API IArchive :: SecurityDescriptor

bool complianceDevice = arch.ComplianceDevice; uint itemCount = (uint) arch.ItemCount;

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

Syntax HRESULT SecurityDescriptor([in] VARIANT newVal);

Parameters [in] VARIANT newVal

New value of the security descriptor.

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

145

146

Content Management API IArchive :: SecurityDescriptor

Version information At Enterprise Vault 8.0, this property is superseded by the IArchive3::SecurityDescriptor property. See “IArchive3 :: SecurityDescriptor” on page 157.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

newVal is invalid, or the object is already populated.

Example To create a security descriptor: char aszPrompt[MAX_INPUT_BUFFER]; wcout parray = SecurityDescSafeArrayOfBytes.Detach();

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

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

Parameters [out, retval] VARIANT_BOOL* pVal

Pointer to a VARIANT_BOOL which will contain the current value.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, or the object has not been populated.

147

148

Content Management API IArchive :: ItemCount

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Example arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get(); string name = arch.Name; string description = arch.Description; EV_STG_API_EXPIRE_ITEMS evEI = arch.ExpireItems; EV_STG_API_CONVERTED_CONTENT evCC = arch.ConvertedContent; EV_STG_API_INDEX_URGENCY evIU = arch.IndexUrgency; EV_STG_API_INDEX_LEVEL evIL = arch.IndexLevel; ulong size = (ulong) arch.Size; bool complianceDevice = arch.ComplianceDevice; uint itemCount = (uint) arch.ItemCount;

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

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

Parameters [out,retval] VARIANT* pVal

Pointer to a VARIANT that will contain the current number of items in the archive.

Content Management API IArchive :: Create

149

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, or the object has not been populated.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Example arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get(); string name = arch.Name; string description = arch.Description; EV_STG_API_EXPIRE_ITEMS evEI = arch.ExpireItems; EV_STG_API_CONVERTED_CONTENT evCC = arch.ConvertedContent; EV_STG_API_INDEX_URGENCY evIU = arch.IndexUrgency; EV_STG_API_INDEX_LEVEL evIL = arch.IndexLevel; ; ulong size = (ulong) arch.Size; bool complianceDevice = arch.ComplianceDevice; uint itemCount = (uint) arch.ItemCount;

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

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, ‘Can manage Enterprise Vault Stores’. By default, the Enterprise Vault Storage Administrator and Power Administrator roles include this operation. Before calling this method, the following properties must be set: ■

VaultStoreId

■

Name

■

IndexUrgency

■

ConvertedContent

■

ExpireItems

■

IndexLevel

The following combination of ConvertedContent and IndexUrgency values are not permitted: ■

CONVERTED_CONTENT_STORED and INDEX_ITEMS_DEFER_INDEFINITELY

■

CONVERTED_CONTENT_ON_DEMAND and INDEX_ITEM_IMMEDIATELY

If the archive is created successfully, the Id property will be populated with the archive Id from the Enterprise Vault Directory. When an archive is created, it is always created as an Enterprise Vault shared archive. See “IArchive3 :: Type” on page 162.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

Content Management API IArchive :: Create

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

CONTENTMANAGEMENTAPI_E_NO_ACCESS

Caller not in a role that includes the operation, ‘Can manage Enterprise Vault Stores’. (The default Enterprise Vault Storage Administrator and Power Administrator roles include this operation).

Examples [C++] archiveName = L"XYZRM_"; archiveName += username; archive->put_Name(archiveName); archive->put_Description(CComBSTR(L"XYZ RM application archive")); archive->put_VaultStoreId(CComBSTR(L"181E669473B52E64384C9A7D9EACA0 E7E1210000evsite")); archive->put_ExpireItems(EXPIRE_ITEMS); archive->put_IndexLevel(INDEX_LEVEL_FULL); archive->put_ConvertedContent(CONVERTED_CONTENT_STORED); archive->put_IndexUrgency(INDEX_ITEMS_IMMEDIATELY); archive->Create(); archive->get_Id(&archiveId); // Remember the assigned Id for future insertions [C#] archive.Name = "XYZRM_" + userName; archive.Description = "XYZ RM application archive"; archive.VaultStoreId = "181E669473B52E64384C9A7D9EACA0E7E1210000evsite"; archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;

151

152

Content Management API IArchive :: Get

archive.IndexLevel = EV_STG_API_INDEX_LEVEL.INDEX_LEVEL_FULL; archive.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.CONVERTED_CONTENT_STORED; archive.IndexUrgency =EV_STG_API_INDEX_URGENCY.INDEX_ITEMS_IMMEDIATELY; archive.Create(); archiveId = archive.Id; // Remember the assigned Id for future insertions

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

Syntax HRESULT Get(void)

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The Id property is empty.

CONTENTMANAGEMENTAPI_E_NOT_FOUND

The archive does not exist.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Example arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";

Content Management API IArchive2 :: Type

arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch.Get(); string name = arch.Name; string description = arch.Description; EV_STG_API_EXPIRE_ITEMS evEI = arch.ExpireItems; EV_STG_API_CONVERTED_CONTENT evCC = arch.ConvertedContent; EV_STG_API_INDEX_URGENCY evIU = arch.IndexUrgency; EV_STG_API_INDEX_LEVEL evIL = arch.IndexLevel; ulong size = (ulong) arch.Size; bool complianceDevice = arch.ComplianceDevice; uint itemCount = (uint) arch.ItemCount;

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

Syntax HRESULT Type([out, retval] EV_STG_API_ARCHIVE_TYPE* pVal);

Parameters [out, retval] EV_STG_API_ARCHIVE_TYPE* pVal

Pointer to an EV_STG_API _ARCHIVE_TYPE that contains the current value.

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

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

153

154

Content Management API IArchive2 :: Status

Return value S_OK

Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

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

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

Parameters Pointer to an EV_STG_API _STATUS that contains the current value.

[out, retval] EV_STG_API_STATUS* pVal

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

Return value S_OK

Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example IArchive2 arch2 = cmAPI.Archive2; arch2.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch2.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch2.Get(); EV_STG_API_STATUS evStatus = arch2.Status;

Content Management API IArchive2 :: HasFolders

if (evStatus == EV_STG_API_STATUS. STS_AVAILABLE) { //store some items

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

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

Parameters [out, retval] VARIANT_BOOL* pVal

Pointer to a VARIANT_BOOL that contains the current value.

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

Return value S_OK

Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example IArchive2 arch2 = cmAPI.Archive2; arch2.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch2.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; bool hasFolders = arch2.HasFolders; if (hasFolders == true)

155

156

Content Management API IArchive2 :: Full

{ //do something

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

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

Parameters [out, retval] VARIANT_BOOL* pVal

Pointer to a VARIANT_BOOL that contains the current value.

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

Return value S_OK

Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example IArchive2 arch2 = cmAPI.Archive2; arch2.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch2.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; bool full = arch2.Full; if (!full) { //store some items

Content Management API IArchive2 :: DirectoryDNSAlias

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

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

Parameters [out, retval] BSTR* pVal

Pointer to a string containing the current DNS alias for the Enterprise Vault Site.

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

Return value S_OK

Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example IArchive2 arch2 = cmAPI.Archive2; arch.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; string dnsAlias = arch2.DirectoryDNSAlias;

IArchive3 :: SecurityDescriptor This property contains the self-relative security descriptor associated with an existing archive, or to be used when creating an archive. This property represents the manually set permissions of the archive, which are displayed on the Permissions tab of the archive properties dialog in the Enterprise Vault Administration Console.

157

158

Content Management API IArchive3 :: SecurityDescriptor

The property is read/write. We recommend that you use the SecurityDescriptorString property to retrieve and set the security descriptor from applications. See “IArchive3 :: SecurityDescriptorString” on page 159.

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

Parameters [out, retval] VARIANT pVal

Pointer to a VARIANT structure that will hold the returned security descriptor value.

[in] VARIANT newVal

New value of the security descriptor.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal is invalid, or the object is already populated.

Content Management API IArchive3 :: SecurityDescriptorString

Example This example illustrates how to fetch the SecurityDescriptor property value. [C++] CComPtr pArchive; // Get an instance of an IArchive3 object to populate pCmAPI->get_Archive(&pArchive); CComQIPtr pArchive3(pArchive); if (pArchive3 != NULL) { pArchive3->put_Id(CComBSTR(L"240A579483C52B89384A9D7D9EACA0E7E 9350000evsite"); pArchive3->put_VaultStoreId(CComBSTR(L"181E669473B52E64384C9A7 D9EACA0E7E1210000evsite")); // Retrieve Archive information // pArchive3->Get(); // Fetch the SecurityDescriptor property value associated with archive // CComVariant varSecurityDescriptor; pArchive3->get_SecurityDescriptor(&varSecurityDescriptor); }

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

159

160

Content Management API IArchive3 :: SecurityDescriptorString

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

Parameters [in] BSTR newVal

The security descriptor value formatted as a text string which conforms to the Security Descriptor string format.

[out, retval] BSTR* pVal

Pointer to a string that will hold the returned security descriptor value.

Remarks If specified, this property must be set before calling the Create archive method. Any attempt to change this value on an existing archive will result in an error. The value of the SecurityDescriptorString property must conform to the MSDN Security Descriptor String Format. For example, "O:AOG:DAD:(A;;RPWPCCDCLCSWRCWDWOGA;;;S-1-0-0)". For information on how to create Security Descriptor strings, see the MSDN Security Descriptor String Format article: http://msdn.microsoft.com/en-us/library/aa379570.aspx The following permissions will be applied to the archive being created based on the supplied SecurityDescriptorString BSTR property values: ■

If the supplied BSTR value is NULL, then the archive is created without any permissions.

■

If the supplied BSTR value is an empty (zero length) string, then the user creating the archive is given full access to the archive.

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

Content Management API IArchive3 :: SecurityDescriptorString

descriptor, and a ToString method, which converts a security descriptor to a string format.

Security descriptor strings using .NET managed code String type and StringBuilder class are available for constructing the SecurityDescriptorString property values. In addition, the ConvertStringSecurityDescriptorToSecurityDescriptor and ConvertSecurityDescriptorToStringSecurityDescriptor functions are available.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal is invalid, or the object is already populated.

Examples The following security descriptor string indicates a user who has been granted full permissions access (Read+Write+Delete) to an archive: "D:(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-201182662-6419)"

This example shows the value associated with the Manual security descriptor setting for the archive to which the user has full permissions access. The following example includes the access described in the example above, and in addition a group has been granted full permissions access ( Read+Write+Delete) on the archive: "D:(A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-2011822662-6419) (A;;CCDCLCSW;;;S-1-5-21-2986758783-3322231649-3643854221-1255)"

The following example includes the access described in the first example above, and in addition a group have been denied full permissions access (Read+Write+Delete) on the archive: "D:(D;;CCDCLCSW;;;S-1-5-21-2986758783-3322231649-3643854221-1255) (A;;CCDCLCSW;;;S-1-5-21-2457296135-1045600968-2011822662-6419)"

161

162

Content Management API IArchive3 :: Type

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

Syntax HRESULT Type([in] EV_STG_API_ARCHIVE_TYPE newVal); HRESULT Type([out, retval] EV_STG_API_ARCHIVE_TYPE* pVal);

Parameters [in] EV_STG_API_ARCHIVE_TYPE newVal

The new value of Type.

[out, retval] EV_STG_API_ARCHIVE_TYPE* pVal

Pointer to an EV_STG_API _ARCHIVE_TYPE that contains the current value.

Remarks Currently, newVal can only be set to ARCHIVE_TYPE_SHARED; any other value is treated as invalid. Any attempt to change this value on an existing archive will result in an error. EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive. See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 77. The value of the property IArchive::HasFolders will be implied from the Type property value. Table 4-20 shows the implied values. False means that the archive is flat. True means that the archive is structured. Table 4-20

Structure of archive types

EV_STG_API_ARCHIVE_TYPE value

HasFolders property value

ARCHIVE_TYPE_SHARED

False

ARCHIVE_TYPE_EXCHANGE_MAILBOX

True

ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER

True

ARCHIVE_TYPE_EXCHANGE_JOURNAL

False

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.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, newVal is invalid, the object is already populated.

Example [out] IArchive3 arch3 = cmAPI.Archive3; arch3.VaultStoreId = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite"; arch3.Id = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; arch3.Get(); EV_STG_API_ARCHIVE_TYPE evType = arch3.Type; if (evType == EV_STG_API_ARCHIVE_TYPE. ARCHIVE_TYPE_EXCHANGE_MAILBOX) { // do something [in] IArchive3 arch3 = cmAPI.Archive3; arch3.Name = "my new archive"; arch3.Description = "my new archive description";

163

164

Content Management API Items object

arch3.ExpireItems = EV_STG_API_EXPIRE_ITEMS. DONT_EXPIRE_ITEMS; arch3.ConvertedContent = EV_STG_API_CONVERTED_CONTENT. CONVERTED_CONTENT_STORED; arch3.IndexUrgency = EV_STG_API_INDEX_URGENCY. INDEX_ITEMS_IMMEDIATELY; arch3.IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL; arch3.Type = EV_STG_API_ARCHIVE_TYPE. ARCHIVE_TYPE_SHARED; arch.Create();

Items object This object implements the following interface: ■

IItems

The IItems interface inherits the properties and methods of the ICollectionBase interface. This interface enables external applications to enumerate the items in an archive in order to retrieve details of each item from the Enterprise Vault Directory.

Syntax interface IItems : ICollectionBase

Member summary Table 4-21

IItems properties

Property

Read/Write

Description

ArchiveId

Read/Write

The ID of the archive holding the items to enumerate.

StartSequenceNum Read/Write

The starting item sequence number to be used when fetching a collection of item records.

OrderBy

The index sequence number ordering to be used when enumerating items in the collection.

Read/Write

The properties and methods of the ICollectionBase interface are described in later sections. See Table 4-9 on page 108.

Content Management API Items object

See Table 4-10 on page 108. Table 4-22

ICollectionBase properties

Property

Read/Write

Description

Count

Read only

Number of items in the collection.

_NewEnum

Read only

Instance of the standard COM enumerator for the collection.

Item

Read only

Instance of the item at the zero-based index into the collection.

Maximum

Read/Write

Maximum number of items in the collection.

More

Read only

Whether or not there were more items than Maximum.

Table 4-23

ICollectionBase methods

Method

Description

Get

Populate the collection.

Clear

Clear the current collection.

Reset

Reset the object back to the initial state.

Remarks Calling applications must have at least Read access to the target archive. The following properties are populated for each Item object in the collection. If additional properties are required for an Item, the Get method should be called specifying the required detail level. ■

IItem::Id

■

IItem::ArchiveId

■

IArchiveMetaData2::SequenceNum

■

IArchiveMetaData2::CurrentLocation

■

IArchiveMetaData2::CurrentFolderId

■

IArchiveMetaData::RetentionCategory

■

IItem::CopyOptions

165

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, if this has been enabled. The soft delete functionality is enabled using the Enterprise Vault Administration Console; by selecting the archive setting, Enable recovery of user deleted items, in Site properties.

Version information ■

This interface requires Enterprise Vault 8.0 or later.

Example This example creates an Items collection object, enumerates the required items in the target archive and retrieves details of the items from the Enterprise Vault Directory. [C++] // Get empty items collection for populating CComPtr spCMAPI; spCMAPI.CreateInstance(CComBSTR(L"EnterpriseVault.ContentManagement API")); CComPtr spUnk; VARIANT_BOOL vbMore = VARIANT_TRUE; ULONGLONG LastSequenceNum; // Get an Items object for enumeration spCMapi->get_Items(&spUnk); CComQIPtr spItems(spUnk); // Populate the Items collection spItems->put_ArchiveId (CComBSTR("1C51F75FFC26EC840A012AD322C579 3AF1e10000LAGUNA4.REA.RND.SYM.COM")); spItems->put_StartSequenceNum (1) // [Min = 1] spItems->put_Maximum(500) // [Max = 10,000] (Comment: Ref ICollectionBase :: Maximum)

Content Management API Items object

spItems->put_OrderBy(ITEMS_ORDERBY_ASC) // Ascending do { CComPtr spItem; // Fetch a batch of items spItems->Get(); // Process each item in collection long lCount = 0; spItems->get_Count(&lCount); // Iterative loop for(long idx = 0; idx < lCount; ++idx) { CComPtr spUnk; //Fetch item spItems->get_Item(idx, &spUnk); CComQIPtr spItem(spUnk); //Do something spItem->Get(DETAIL_LEVEL_ITEM_CONTENT | DETAIL_LEVEL_ARCHIVE_METADATA); ... // Remember the last item seq. no. CComPtr spAMD; spItem->get_ArchiveMetaData(&spAMD); CComQIPtr spAMD2(spAMD); spAMD2->get_SequenceNum(&LastSequenceNum) } vbMore = spItems->More(); // Fetch next chunk of items if (vbMore) { // Reset start sequence no to last item's sequence no. (of previous collection) + 1 spItems->put_StartSequenceNum = LastSequenceNum+1;

167

168

Content Management API IItems :: ArchiveId

} } while (vbMore)

See also ■

See “Enumerating vault stores, archives and items” on page 70.

■

See “ICollectionBase : IDispatch” on page 308.

■

See “Item object” on page 172.

■

See “ArchiveMetaData object” on page 225.

■

See “Content object” on page 212.

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

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

Parameters [in] BSTR newVal

The ID of the target archive. Maximum length of string: 127 characters.

[out, retval] BSTR* pVal

Pointer to a BSTR that will contain the ID of the current archive.

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

Content Management API IItems :: StartSequenceNum

169

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL or newVal is not a valid archive identity.

Example IContentManagementAPI4 cmAPI4 = new agementAPIClass();

(IContentManagementAPI4)ContentMan

IItems items = cmAPI4.Items; items.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; items.StartSequenceNum = 1000; items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC; items.Get();

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

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

Parameters [in] ULONGLONG newValue

Index sequence number of the first item in the required items collection.

[out,retval] ULONGLONG* pVal

Integer that will receive the index sequence number of the first item in the collection.

170

Content Management API IItems :: OrderBy

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

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL or newVal is not a valid archive identity.

Example IContentManagementAPI3 cmAPI3 = new

(IContentManagementAPI3)ContentManagementAPIClass();

IItems items = cmAPI3.Items; items.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; items.StartSequenceNum = 1000; items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC; items.Get();

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

Content Management API IItems :: OrderBy

171

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

Parameters [in] EV_API_ITEMS_ORDERBY newVal

The index sequence number order to use when enumerating the item collection.

[out,retval] EV_API_ITEMS_ORDERBY* pVal

The index sequence number order used when enumerating the current item collection.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL or newVal is invalid.

Example IContentManagementAPI4 cmAPI4 = new

(IContentManagementAPI3)ContentManagementAPIClass();

IItems items = cmAPI4.Items; items.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; items.StartSequenceNum = 1000; items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC; items.Get();

172

Content Management API Item object

Item object This object implements the following interfaces: ■

IItem IID is {D96AF252-8216-4907-AF6B-7DBC93028694}

■

IItem2 IID is {9F6D061C-A8E9-4937-8592-762F23B037CA}

■

IItem3 IID is {E5C7F710-36AD-4e24-B00A-E3D709FF76CD}

This object enables the storage and management of items in Enterprise Vault archives. The IItem2 interface provides an additional property to help determine why an item no longer exists in an archive. The IItem3 interface provides an additional method to recover an item that has been soft-deleted.

Syntax interface IItem : IDispatch

Member summary Table 4-24

IItem properties

Property

Read/Write

Description

ArchiveId

Read/Write

Archive ID of the archive containing the required item.

Id

Read/Write

Identifier of the item in the archive.

Content

Read only

Instance of a Content object that provides access to the data that is to be archived, or has been archived.

ArchiveMetaData

Read only

Pointer to an IArchiveMetaData object that provides details of how the item will be, or has been archived.

BrowserViewURL

Read only

URL for viewing the archived item.

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, where the original format has not been stored.

Holds

Read only

Enables the enumeration of legal holds placed on the archived item.

NativeItemURL

Read only

URL for downloading the archived item. The item is opened in the default application for the type of item.

DeletionLevel

Read/Write

Indicates whether deleting the item deletes it completely (hard delete) or moved to the Enterprise Vault "dumpster" (soft delete).

CopyOptions

Read/Write

Identifies source item property values to be copied to the destination item.

Table 4-25

IItem methods

Methods

Description

Get

Retrieves archived item, or information about an archived item.

Delete

Delete item from archive.

CanBeDeleted

Check if archived item can be deleted.

CopyTo

Copy archived item to another location.

MoveTo

Move archived item to another location.

Insert

Stores item in an archive.

Table 4-26

IItem2 property

Property

Read/write

Description

DeletionReason

Read only

If the item no longer exists in the archive, this property can be used to discover why the item was deleted.

173

174

Content Management API IItem :: ArchiveId

Table 4-27

IItem3 method

Property

Description

Undelete

Recover an item that has been soft-deleted.

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

Version information ■

CopyOptions property requires Enterprise Vault 8.0.

■

IItem2 interface requires Enterprise Vault 8.0 SP3.

■

IItem3 interface requires Enterprise Vault 9.0.

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

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

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

Parameters [in] BSTR newVal

The Archive ID of the archive. Maximum length of string: 127 characters.

Content Management API IItem :: Id

[out, retval] BSTR* pVal

Pointer to a BSTR that will contain the ID of the current archive.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL, or newVal is not a valid Archive Id.

Example [C#] IItem itm = cmAPI.Item; itm.ArchiveId = ""181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; itm.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7 9f3298dc8a1e60"; itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);

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

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

175

176

Content Management API IItem :: Id

Parameters [in] BSTR newVal

Id of stored item.

[out,retval] BSTR* pVal

Pointer to a BSTR that will contain the current value of this item's ID.

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

Version information Enterprise Vault 7.0 or later is required to support a Transaction ID value for this property.

Return value S_OK

Success.

S_FALSE

Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

Examples [C++] CComBSTR bstr(L"161000000000000~200501051649270000~0~9039eb282e3d4 083b79f3298dc8a1e60")

Content Management API IItem :: Content

item->put_Id(bstr); //DO Get and check the id bstr.Clear(); item->get_Id(&bstr); [C#] IItem item = cmAPI.Item; item.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7 9f3298dc8a1e60"; itm.Archive.Id = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);

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

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

Parameters [out,retval] IContent** pVal

Instance of a Content object.

Remarks The IContent interface makes the following properties available. Each of these is described in more detail in the relevant section. ■

Title

■

OriginalLocation

■

FileExtension

177

178

Content Management API IItem :: ArchiveMetaData

■

MimeFormat

■

CreatedDate

■

ModifiedDate

■

Data

■

OriginalSize

■

Author

See “Content object” on page 212.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Examples [C++] IContent* pContent = NULL; item->get_Content(&pContent); [C#] item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES); IContent content= item.Content; LogContentProperties(content, item.Id);

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

Syntax HRESULT ArchiveMetaData([out, retval] IArchiveMetaData**

pVal);

Content Management API IItem :: BrowserViewURL

Parameters [out,retval] IArchiveMetaData** pVal

Pointer to an IArchiveMetaData pointer.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pVal is NULL.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData;

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. The property is read only.

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

179

180

Content Management API IItem :: BrowserViewURL

Parameters [out,retval] BSTR* pVal

Pointer to a BSTR that will contain the URL.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory Service is not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Examples [C++] CComBSTR bstr; item->put_Id(L"161000000000000~200501051649270000~0~9039eb282e3d408 3b79f3298dc8a1e60"); item->put_ArchiveId("181E669473B52E64384C9A7D9EACA0E7E1110000evsi

Content Management API IItem :: DefaultMSGFormat

te"); item->get_BrowserViewURL(&bstr); [C#] item.Id = "161000000000000~200501051649270000~0~9039eb282e3d4 083b79f3298dc8a1e60"; Item.arhiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; String url = Item.BrowserViewURL;

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

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

Parameters [in] BSTR newVal

New value to be set. See Remarks below.

[out,retval] BSTR* pVal

Pointer to a BSTR that will hold the current value.

Remarks The following values can be assigned to newVal: "N"

Perform no conversion.

"U"

Return as Unicode.

"A:"

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

181

182

Content Management API IItem :: DefaultMSGFormat

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to change an existing value.

Examples [C++] item->put_DefaultMSGFormat(L"U"); //do something, put ids etc Item->Get(DETAIL_LEVEL_ALL); Itm->put_DefaultMSGFormat(L"N"); [C#] itm.DefaultMSGFomart = "U"; //do something - set ids etc

//

ERROR

Content Management API IItem :: Holds

Itm.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ALL)); Itm.=defaultMSGFormat = "N"; //ERROR

IItem :: Holds This property gives access to the set of holds currently placed on the item. The property is read only. See “Holds object” on page 285.

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

Parameters [out,retval] IHolds** pVal

Pointer to an IHolds pointer which will contain the current IHolds pointer.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or could not find the HOLDS collection.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";

183

184

Content Management API IItem :: NativeItemURL

item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA); IHolds holds = Item.Holds;

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

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

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

Remarks There will be an error if either the item Id or the archive Id have not been set before using this property. 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.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or either the Item Id or Archive Id have not been set.

Examples [C++]

Content Management API IItem :: DeletionLevel

185

CComBSTR bstr; item->put_Id(L"200501051649270000~0~9039eb282e3d4083b79f3298 dc8a1e60") item->put_ArchiveId(L"181E669473B52E64384C9A7D9EACA0E7E11100 00evsite"); item->get_NativeItemURL(&bstr);

[C#] item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; string url = item.NativeItemURL;

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

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

Parameters [in] EV_API_DELETION_LEVEL newVal

New EV_API_DELETION_LEVEL value.

[out,retval] EV_API_DELETION_LEVEL* pVal

Current EV_API_DELETION_LEVEL value.

Remarks EV_API_DELETION_LEVEL is an enumerated value. See “EV_API_DELETION_LEVEL enumeration” on page 75. The default value for this property is DELETION_LEVEL_SOFT_DELETE. For a period of time after deletion (configured by the administrator), users can recover a soft-deleted item.

186

Content Management API IItem :: DeletionLevel

In the Enterprise Vault Administration Console, in the Site Properties pages, the administrator can enable the recovery of deleted items and specify how long soft-deleted items are to be kept. The Item Undelete method can be used to recover a soft-deleted item. See “IItem3 :: Undelete” on page 210.

Version information ■

The ability to retrieve deleted items in Enterprise Vault is available from Enterprise Vault 2007.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or newVal is invalid.

Example [in] item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; item.DeletionLevel = EV_API_DELETION_LEVEL. DELETION_LEVEL_SOFT_DELETE; IContent content = item.Content; content.Title = "New title"; content.FileExtension = "msg"; content.OriginalLocation = "Inbox"; content.Data = "C:\\temp\\test.msg"; item.Insert(); [out] IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES); EV_API_DELETION_LEVEL evDL = item.DeletionLevel;

Content Management API IItem :: CopyOptions

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

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

Parameters [in] EV_STG_API_ITEM_COPYOPTIONS newVal

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

[out,retval] EV_STG_API_ITEM_COPYOPTIONS* pVal

Current bit mask value.

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

SimpleIndexMetadata

■

ArchivedDate

187

188

Content Management API IItem :: CopyOptions

■

RetentionCategory

■

CurrentLocation

■

CurrentFolder

■

CustomIdentifier

■

CustomQualifier

■

CustomProperties

See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 82.

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

Effect of setting override item property values with ITEM_COPYOPTIONS_ARCHIVEMETADATA enumeration value

Item property

Option selected

Override value set Property value in on destination item copied item

ArchivedDate

Yes (Default)

Yes

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

No

Yes

As above.

Yes (Default)

No

Copied from source item.

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.

RetentionCategory Yes (Default)

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

Yes

As above.

Yes (Default)

No

Copied from source item.1

No

No

Set to the site default Retention Category.

Yes

Set to override value.2

CustomIdentifier Yes (Default) CustomQualifier CustomProperties

CurrentLocation CurrentFolderId

Set to zero value if override specified as zero value.

No

Yes

As above.

Yes (Default)

No

Copied from source item.

No

No

Set to zero value.

Yes (Default)

Yes

Set to override value.

No

Yes

See “IArchiveMetaData2 :: CurrentLocation” on page 245.

Yes (Default)

No

Copied from source item.3

189

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.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to set the CopyOptions of an existing item, or the value set is not within enumeration.

Example In the following VBScript example, the source item's ArchiveMetaData values are preserved on the destination item. Dim ecmAPI Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI") Dim oItem, oDestItem

Content Management API IItem :: Insert

‘ Establish the source item Set oItem = ecmAPI.Item ‘ Establish the destination item Set oDestItem = ecmAPI.Item oDestItem.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite" ‘ Set the CopyOptions flags to set the copied item's TransactionId ‘ and ArchiveMetaData values ‘ from the source item (Ref EV_STG_API_ITEM_COPYOPTIONS) oDestItem.CopyOptions = 2 oItem.CopyTo (oDestItem)

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

Syntax HRESULT Insert(void);

Remarks It is important to make sure that this interface pointer has not been used before to perform an Insert or Get action. The caller must have WRITE access permissions on the destination archive. Otherwise, an error will occur. For structured archives, the caller must have write access to the destination archive folder. If an override value is specified for the ArchivedDate property, the calling application must be in an Enterprise Vault role that includes the operation, "{API} Can Use Extended API Features". This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles. The Insert method stores an item in the specified archive. Before calling Insert, the following properties must be populated: ■

IItem :: ArchiveId

191

192

Content Management API IItem :: Insert

■

IContent :: Data

■

Either IContent :: FileExtension or IContent :: MIMEFormat. Enterprise Vault uses the supplied extension or MIME type to enhance indexing and storage functionality for content types such as Outlook messages. If you assign any other values to an item, Enterprise Vault archives and indexes the item as a file. Enterprise Vault provides enhanced indexing and storage functionality for the following content types: ■

Outlook messages, which have a file extension of .msg and a MIME format of application/vnd.ms-outlook.

■

SMTP messages, which have a file extension of .eml and a MIME format of message/rfc822.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

Content Management API IItem :: Insert

CONTENTMANAGEMENTAPI_E_BUSY

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

CONTENTMANAGEMENTAPI_E_NOT_FOUND

The target Archive Id is unknown or has been deleted, or the selected retention category is not known or has been deleted.

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL

The target archive is full or exceeds its quota limit.

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. ■ The archive is in a read-only state. ■

■

CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID

An override value has been specified for ArchivedDate, but the caller is not in a role that includes the operation, "{API} Can Use Extended API Features". (The default Enterprise Vault Storage Administrator and Power Administrator roles include this operation).

Item Id is not unique in the target vault store.

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER Attempting to insert items into a structured archive containing multiple root folders (for example, a public folder archive).

Examples [C++] spItem.put->ArchiveId(L"181E669473B52E64384C9A7D9EACA0E7E1110000evs ite"); IContent* pContent = null; spItem->get_Content(&pContent); pContent->put_Title(L"new title"); pContent->put_FileExtension(L"msg"); pContent->put_Data(L"C:\\temp\\test.msg"); spItem->Insert(); [C#] item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = item.Content;

194

Content Management API IItem :: Get

content.Title = "New title"; content.FileExtension = "msg"; content.Data = "C:\\temp\\test.msg"; item.Insert();

See also See “Content object” on page 212.

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

Syntax HRESULT Get([in] LONG DetailLevel);

Parameters [in] LONG DetailLevel

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

Remarks The item's ArchiveId and either its Id property or IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier properties must be set prior to calling this method. When retrieving hold data only, the item's Id property must be used (DetailLevel = DETAIL_LEVEL_HOLD_DATA). The item's CustomIdentifier and CustomQualifier properties can only be used when together they uniquely identify an item. See “IIArchiveMetaData :: CustomIdentifier” on page 239. EV_STG_API_ITEM_DETAIL indicates the data to retrieve for an item. See “EV_STG_API_ITEM_DETAIL enumeration” on page 83. The caller can "bitwise OR" the bit masks together. For example, IItem.Get(255) returns the item properties and the metadata.

Content Management API IItem :: Get

If the soft delete feature has been enabled, items that have been soft deleted from the archive are retrieved. The soft delete functionality is enabled using the Enterprise Vault Administration Console; by selecting the archive setting, Enable recovery of user deleted items, in Site properties. To retrieve the item content, the caller must populate the IContent::Data property with a file location on disk, or to an IStream or ILockbytes object that has been created ready to receive the item content. Note: If you specify a file, any existing content will be overwritten. The Content Management API supports IStream and ILockBytes implementations where the input data length provided by the Stat method is not known. See “IContent :: Data” on page 220. When DETAIL_LEVEL__SYSTEM_INDEXDATA is requested, the "cont" property is included in the properties returned. This is the HTML representation (converted content) of the item or attachment. If the size of the item's converted content is larger than 5MB, then the converted content is not returned. Instead, a content missing reason ("comr") property is returned with the reason, vmrVALUENOTOBTAINED (2). This limit can be changed using the registry setting: HKEY_LOCAL_MACHINE \Software \Wow6432Node \KVS \Enterprise Vault \MaxIndexDataHTMLContentKB

This registry setting is described in the Registry Values guide.

Return values S_OK

Success.

195

196

Content Management API IItem :: Get

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pointer passed in is NULL, or the item's Archive Id and either its Id property, or CustomIdentifier and CustomQualifier properties, have not been set.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

CONTENTMANAGEMENTAPI_E_NOT_FOUND

The target Archive Id is unknown or has been deleted, or the selected item is not present or has been deleted.

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.

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.0 SP4 and Enterprise Vault 7.0 SP2. See “Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4” on page 42. Note that this feature requires MSXML 3.0 or later.

■

When the enumerated value, DETAIL_LEVEL_ITEM_CONTENT, is included as part of the input parameter for IItem::Get, the correct date and time is now returned by IContent::ModifiedDate and IContent::CreatedDate. This is fixed in Enterprise Vault 6.0 SP4 and Enterprise Vault 7.0 SP2, and later. See “Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4” on page 42.

■

IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier require Enterprise Vault 8.0. See “Enterprise Vault 8.0” on page 34.

Examples Refer to Microsoft documentation for details and usage of IStorage and IStream. [C++] item->put_Id( L" 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"); item->put_ArchiveId(L"181E669473B52E64384C9A7D9EACA0E7E1110000site" ); IStorage* pStorage = NULL; StgCreateStorageEx(NULL, STGM_READWRITE | STGM_CREATE, STGFMT_FILE, 0, NULL, 0, NULL, IID_IStorage, reinterpret_cast(&pStorage)); IStream* pStream = NULL; pStorage->CreateStream(\xe3 Test Stream", STGM_READSWRITE | STGM_CREATE, 0, 0, &pStream); IContent* pContent = NULL; item->get_Content(&pContent); pContent->put_Data(pStream); item->Get(DETAIL_LEVEL_ITEM_CONTENT);

197

198

Content Management API IItem :: Delete

//do something pStream->Release(); pStream = NULL; pStorage->Release(); pStorage = NULL; pContent->Release(); pContent = NULL; item->Release(); item = NULL; [C#] item.Id = " 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; Item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = null; content = item.Content; content.Data = "C:\\temp\\temp.msg"; item.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_CONTENT)); //do something

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

Syntax HRESULT Delete(void);

Remarks Calling the Delete method will remove the item from its archive. The value of the DeletionLevel property will determine whether a hard or soft delete is performed. Prior to calling this method, the application programmer must have set the ArchiveId (to identify the archive containing the item), and the Id property to identify the item within its container. It cannot be called on an item whose ArchiveId and Id properties have not been set, as this will cause an error.

Content Management API IItem :: Delete

The calling user must have the appropriate permissions to delete the item. It is also possible that the server will reject the request because an item is "On Hold" or cannot be removed for compliance reasons.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

A NULL pointer has been passed in, or either the Archive Id or Item Id have not been set.

CONTENTMANAGEMENTAPI_E_NOT_FOUND

The target Archive Id is unknown or has been deleted.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

CONTENTMANAGEMENTAPI_E_NO_ACCESS

The caller does not have delete access to the target archive or archive folder,or the archive is in a read-only state.

CONTENTMANAGEMENTAPI_E_DELETION_BARRED

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

Examples [C++] item->put_Archive_Id(L"181E669473B52E64384C9A7D9EACA0E7E1110000evsi te"); item->putId(L"181E669473B52E64384C9A7D9EACA0E7E1110000evsite");

199

200

Content Management API IItem :: CanBeDeleted

item->Delete(); [C#] IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES); object obj = item.CanBeDeleted; int canBeDeleted = (int)obj; if (obj == 0) { item.Delete(); }

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

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

Parameters [out,retval] VARIANT* CanDelete

Pointer to a VARIANT containing the current value.

Remarks CanBeDeleted returns a value to indicate whether or not the item can be deleted. See “EV_STG_API_CAN_DELETE enumeration” on page 78.

Return value S_OK

Success.

Content Management API IItem :: CopyTo

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

CONTENTMANAGEMENTAPI_E_NOT_FOUND

The target Archive Id is unknown or has been deleted, or the selected item is not present or has been deleted.

CONTENTMANAGEMENTAPI_E_NO_ACCESS

The caller does not have read access to the target archive or archive folder.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES); object obj = item.CanBeDeleted; int canBeDeleted = (int)obj; if (obj == 0) { item.Delete(); }

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

201

202

Content Management API IItem :: CopyTo

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

Parameters [in] IItem* DestinationItem

IItem interface pointer that represents the destination item.

Remarks The source and destination archive and vault store may be different, but the source and destination site must be the same. The caller must have READ access to the source archive, and WRITE access permissions on the destination archive, otherwise an error will occur. For structured archives, the caller must have READ access to the source archive folder and WRITE access to the destination archive folder. If an override value is specified for the ArchivedDate property, the calling application must be in an Enterprise Vault role that includes the operation, "{API} Can Use Extended API Features". This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles. When copying an item: ■

Create the destination item object.

■

Set the ArchiveId on the destination item object.

■

Set CopyOptions properties on the destination item object.

■

Optionally set any ArchiveMetadata override property values if the copy option, ITEM_COPYOPTIONS_ARCHIVEMETADATA, is selected.

The CopyOptions property on the destination item object specifies the item elements to be copied across to the destination item. See “IItem :: CopyOptions” on page 187. From Enterprise Vault 8.0, the default action has changed; the item content and its associated ArchiveMetaData and IndexData elements are copied from the source item. This means that the default behaviour preserves the original ArchivedDate and OriginalLocation on the destination item, if override values are not specified. For backwards compatibility, the calling application can set suitable override values on the destination item object. Important considerations apply when specifying the destination archive folder.

Content Management API IItem :: CopyTo

See “IArchiveMetaData2 :: CurrentLocation” on page 245.

Return value S_OK

Success.

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, but they refer to different archive folders. ■ Either IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set, and the destination archive is a flat archive. ■ The destination site is not the same as the source site. ■

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

CONTENTMANAGEMENTAPI_E_NOT_FOUND

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

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL

The destination archive is full or exceeds its quota limit.

203

204

Content Management API IItem :: CopyTo

CONTENTMANAGEMENTAPI_E_NO_ACCESS

One of the following situations exists: No access to the archive or archive folder. ■ The target archive is in a read-only state. ■ An override value has been specified for ArchivedDate, but the caller is not in a role that includes the operation, "{API} Can Use Extended API Features". (By default, the Enterprise Vault Storage Administrator and Power Administrator roles include this operation). ■

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER

Attempting to copy items to a structured archive containing multiple root folders (for example, a public folder archive).

Examples [C++] IItem* pItemSrc = NULL; pCmAPI->get_Item(&pItemSrc); pItemSrc->put_ArchiveId(CComBSTR(L"181E669473B52E64384C9A7D9EACA0E7 E1110000evsite")); pItmDest->put_ArchiveId(CComBSTR(L"1E1FA1405F674644286ADBD247BA780C B1110000evsite")); pItemSrc->put_Id(CComBSTR(L"334880000000000~200707251102240000~0~D3 962A35951E4B03AE9CFB68AFE1218")); IItem* pItemDst = NULL; pCmAPI->get_Item(&pItemDst); IArchiveMetaData* pDstAMD = NULL; pItemDst->get_ArchiveMetaData(&pDstAMD); pDstAMD->put_RetentionCategory(CComBSTR(L"Business")); IComplianceData* pDstComp = NULL; pDstAMD->get_ComplianceData(&pDstComp); pDstComp->SetBy(SETBY_RETCAT); pItemSrc->CopyTo(pItemDst);

Content Management API IItem :: MoveTo

[C#] IItem itemSrc = cmAPI.Item; IItem itemDst = cmAPI.Item; itemSrc.ArchiveId ="181E669473B52E64384C9A7D9EACA0E7E1110000ev site"; itemDst.ArchiveId = "1E1FA1405F674644286ADBD247BA780CB1110000ev site"; itemSrc.Id ="334880000000000~200707251102240000~0~D3962A35951E4B03 AE9CFB68AFE1218"; itemDst.ArchiveMetaData.RetentionCategory = "Business"; itemDst.ArchiveMetaData.ComplianceData.SetBy = EV_STG_API_CP_SETBY.SETBY_RETCAT; itemSrc.CopyTo(itemDst);

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

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

Parameters [in] IItem* DestinationItem

Pointer to the destination item object.

Remarks The source and destination archive and vault store may be different, but the source and destination site must be the same. The caller must have DELETE access to the source archive and archive folder, and WRITE access permissions on the destination archive and archive folder, otherwise an error will occur. If an override value is specified for the ArchivedDate property, the calling application must be in an Enterprise Vault role that includes the operation, "Can Use Extended API Features". This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles.

205

206

Content Management API IItem :: MoveTo

The MoveTo method is identical to the CopyTo operation, but it additionally removes the source item from the source archive after the copy has completed. See “IItem :: CopyTo” on page 201. The CopyOptions property on the destination item object specifies the item elements to be copied across to the destination item. See “IItem :: CopyOptions” on page 187.

Return value S_OK

Success.

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 but they refer to different archive folders. ■ Either IArchiveMetadata2::CurrentLocation and IArchiveMetadata2::CurrentFolderId have been set and the destination archive is a flat archive. ■ The destination site is not the same as the source site. ■

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

CONTENTMANAGEMENTAPI_E_NOT_FOUND

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

Content Management API IItem :: MoveTo

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL

The destination archive is full or exceeds its quota limit.

CONTENTMANAGEMENTAPI_E_DELETION_BARRED

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

CONTENTMANAGEMENTAPI_E_NO_ACCESS

One of the following situations exists: The caller does not have delete access to the source archive, or archive folder. ■ The caller does not have write access to the destination archive, or archive folder. ■ The source or destination archive is in a read-only state. ■ An override value has been specified for ArchivedDate, but the caller is not in a role that includes the operation, "{API} Can Use Extended API Features". (By default, the Enterprise Vault Storage Administrator and Power Administrator roles include this operation). ■

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER

Attempting to move items to a structured archive containing multiple root folders (for example, a public folder archive).

Example IItem itemSrc = cmAPI.Item; IItem itemDst = cmAPI.Item; itemSrc.ArchiveId ="181E669473B52E64384C9A7D9EACA0E7E1110000ev site"; itemDst.ArchiveId = "1E1FA1405F674644286ADBD247BA780CB1110000ev site"; itemSrc.Id ="334880000000000~200707251102240000~0~D3962A35951E4B03 AE9CFB68AFE1218";

207

208

Content Management API IItem2 :: DeletionReason

itemDst.ArchiveMetaData.RetentionCategory = "Business"; itemDst.ArchiveMetaData.ComplianceData.SetBy = EV_STG_API_CP_SETBY.SETBY_RETCAT; itemSrc.MoveTo(itemDst);

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

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

Parameters [out,retval] EV_STG_API_DELETION_3REASON* pVal

Current EV_STG_API _DELETION_REASON value.

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

Return value S_OK

Success.

S_FALSE

Success. The default value (NULL) is returned.

Content Management API IItem2 :: DeletionReason

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pointer (pVal) passed in is NULL, or the item's Archive Id or Id property have not been set.

CONTENTMANAGEMENTAPI_E_NO_ACCESS

Caller does not have read access to the archive.

CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND

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

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

209

210

Content Management API IItem3 :: Undelete

{ delReason = destItem.DeletionReason; } finally { // Log that the item was not found together with the // deletion reason LogItemNotFound(destItem, delReason); } } }

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

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

Parameters [out,retval] VARIANT_BOOL* pVal

A value of TRUE indicates that the item has been recovered.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_NOT_FOUND

The target Archive Id has not been found.

Content Management API IItem3 :: Undelete

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pointer (pVal) passed in is NULL, or the item's Archive Id or Item Id property have not been set.

CONTENTMANAGEMENTAPI_E_NO_ACCESS

Caller does not have undelete access to the archive. That is, the caller is not in a role that allows the operation, "Can undelete items in any archive".

CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND

The item could not be found in the archive, or has been removed from the Enterprise Vault dumpster area.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault is currently busy or has insufficient resources to complete the request. This error indicates that the caller should retry later.

Version information ■

IItem3 interface requires Enterprise Vault 9.0.

See also ■

See “IItem :: DeletionLevel” on page 185.

Examples [C#] IItem3 item = (IItem3)cmAPI.Item; item.ArchiveId =

211

212

Content Management API Content object

"118F819534E391C43B6854E2DD3A708C61110000EV.example.com"; item.Id = "201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51 651"; bool UnDeleted = item.Undelete(); [VBScript] Dim ecmAPI, oItem, oItem3 Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI") set oItem = ecmAPI.Item set oItem3 = ecmAPI.IDispatchQueryInterface(oItem,"{E5C7F710-36AD-4e24-B00A-E3D7 09FF76CD}") oItem3.ArchiveId = "118F819534E391C43B6854E2DD3A708C61110000EV.example.com" oItem3.ID = "201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51651" dim results result = oItem3.Undelete if (Err.number 0) then WScript.Echo "Error: " & Err.Description end if if result then WScript.Echo "Item Undeleted" else WScript.Echo "Item has not been Undeleted" end if

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

Content Management API Content object

Syntax interface IContent : IDispatch

Member summary Table 4-29

IContent Properties

Property

Description

Title

The name, title or subject of the item.

OriginalLocation

The original location of the item. Folder hierarchy is represented using back slashes as separators.

FileExtension

File extension describing the format of the item.

MIMEFormat

Optional property describing the MIME file format of the item.

CreatedDate

Optional property that contains the UTC date and time that the item was created.

ModifiedDate

Optional property that contains the UTC date and time that the item was last modified.

Data

The Data property is used to pass the raw content of the item to or from the archive. The parameter can be the path to a file that contains the content to be archived, or an IStream or ILockBytes object containing the content to be archived.

OriginalSize

This property contains the size in bytes of the original item that was archived.

Author

Optional property. The author of the item.

Example item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = item.Content; content.Title = "New title"; content.FileExtension = "msg"; content.OriginalLocation = "Inbox"; content.Data = "C:\\temp\\test.msg"; item.Insert();

213

214

Content Management API IContent :: Title

IContent :: Title This property holds the name, title or subject of the item. The property is read/write.

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

Parameters [out, retval] BSTR* pVal

The title of this item.

[in] BSTR newVal

The new title of this item.

Remarks If an attempt is made to change the title after a call to Insert or Get, an error will occur.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or the title of this item has already been set in a previous call to Insert.

Example [C#] IContent content = itm.Content; string title = content.Title;

IContent :: OriginalLocation This property holds the original location of the item.

Content Management API IContent :: FileExtension

The property is read/write.

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the original location

[in] BSTR newVal

The original location value to be set.

Return value S_OK

Success.

S_FALSE

Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or this property has already been set.

Example item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = item.Content; content.Title = "New title"; content.FileExtension = "msg"; content.OriginalLocation = "Inbox"; content.Data = "C:\\temp\\test.msg"; item.Insert();

IContent :: FileExtension This property holds the file extension describing the format of the item. The property is read/write.

215

216

Content Management API IContent :: FileExtension

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the current file extension.

[in] BSTR newVal

The file extension to use.

Remarks This property describes the format of the item. For example, use ‘ .txt’ where the content is simple text, or ‘.msg’ where the content is in Outlook message file format. It is required so that the item can be indexed when it is archived, and opened correctly by a web browser using IItem :: BrowserViewURL. The default value is ".bin". The preceding period in a file extension can be included or omitted when setting a value. It will be added by the API when the item is archived. Once this value has been set it cannot be changed.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to change an existing value.

Example item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = item.Content; content.Title = "New title"; content.FileExtension = "msg"; content.OriginalLocation = "Inbox";

Content Management API IContent :: MIMEFormat

content.Data = "C:\\temp\\test.msg"; item.Insert();

IContent :: MIMEFormat This property is optional and describes the MIME file format of the item. This property is useful for HTTP Web-based client applications that process byte streams with the MIME type parameter (content-type), rather than files. The property is read/write.

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the current value of the property

[in] BSTR newVal

The new value of the property to be set

Remarks For example, use ‘text/plain’ where the content is simple text, or ‘application/vnd.ms-outlook’ where the content is in Outlook message file format. If the property is set, it cannot be changed after the item has been archived.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to change the value of this property after the item has been archived.

217

218

Content Management API IContent :: CreatedDate

Example item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = item.Content; content.Title = "New title"; content.MIMEFormat = "text/plain"; content.OriginalLocation = "C:\\temp"; content.Data = "C:\\temp\\test.txt"; item.Insert();

IContent :: CreatedDate This property contains the UTC date and time that the item was created. The property is read/write.

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

Parameters [out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the value of the property.

[in] VARIANT newVal

The new value to set this property.

Remarks Once this item has been archived it is not possible to change the value of this property.

Return value S_OK

Success.

Content Management API IContent :: ModifiedDate

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or either an attempt to modify the property value after the item has been archived has been made, or the data passed in is corrupt and of the wrong data type.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES); IContent cont = item.Content; object obj = content.CreatedTime; DateTime dt = (DateTime)obj;

IContent :: ModifiedDate This property contains the UTC date and time that the item was last modified. The property is read/write.

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

Parameters [out, retval] VARIANT* pVal

The UTC date and time that the item was last modified.

[in] VARIANT newVal

Optional property that contains the UTC date and time that the item was last modified.

219

220

Content Management API IContent :: Data

Remarks Once this item has been archived it is not possible to change the value of this property.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or either this property is being modified after the item has been saved in the archive, or the value passed into the property is not in the correct format.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES); IContent cont = item.Content; object obj = content.ModifiedTime; DateTime dt = (DateTime)obj;

IContent :: Data This property is used to pass the raw content of the item to or from the archive. The property is read/write.

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

Content Management API IContent :: Data

221

Parameters [out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the actual item data.

[in] VARIANT newVal

Variant containing the data.

Remarks One important point to remember is that the item data, properties and archive metadata is not archived until the Insert method has been called. This property must be set to the path of a file on disk, or an IStream or ILockBytes object. Note: If you specify a file, any existing content will be overwritten when retrieving an item. If the calling application is a .NET application, and the overhead of saving the item content to a file is not acceptable, you will need to create a managed implementation of the System.Runtime.InteropServices.ComTypes.IStream interface. For example, you can create a .NET class that inherits from System.Runtime.InteropServices.ComTypes.IStream and implements its methods using an instance of a managed stream, System.IO.Stream. The Content Management API supports IStream and ILockBytes implementations where the input data length provided by the Stat method is not known. When using a version of the Enterprise Vault API runtime prior to Enterprise Vault 8.0, .NET applications should ensure the following recommendations are implemented in order to support the insertion or retrieval of items larger than 4MB: ■

The application's entry point, the Main method, is not set to use the COM single-threaded apartment (STA) model.

■

The application's entry point, the Main method, invokes CoInitializeSecurity via PInvoke, with the following parameter values: CoInitializeSecurity(NULL, -1, NULL, NULL, RPC_C_AUTHN_LEVEL_CALL, RPC_C_IMP_LEVEL_IDENTIFY, NULL, EOAC_NONE, NULL);

■

All use of the Content Management API is from threads set to use the COM single-threaded apartment; the Content Management API is not invoked from the application's entry point method.

222

Content Management API IContent :: OriginalSize

Applications where these conditions cannot be met, such as Windows Forms applications, applications hosted by IIS, or any other executable where COM security has already been initialized to restrict remote access, cannot support insert or retrieval of items larger than 4MB.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to modify this property after the item has been stored in the archive.

Example [C#] IContent content = itm.Content; content.Data = "C:\\temp\\temp.msg";

A C# implementation of IStream can be used instead: MemoryStream itemCont = new MemoryStream(); content.Data = (IStream) new ComStreamAdaptor(itemCont);

IContent :: OriginalSize This property returns the size of the original item, in bytes, before it was archived. The property is read only.

Syntax HRESULT OriginalSize([out, retval] VARIANT*

pVal);

Content Management API IContent :: Author

Parameters [out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the value of this property. The VARIANT should have been set to VARTYPE vt = VT_R8

Remarks This property is only available after an item has been archived. No error will be returned if this property is called before archiving and the returned value will be 0.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES); IContent cont = item.Content; object obj = content.OriginalSize; double size = (double)obj;

IContent :: Author This property contains the author of the item. The property is read/write and optional.

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

223

224

Content Management API IContent :: Author

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the current value of this property.

[in] BSTR newVal

The new value of the property to be set

Remarks This is an optional property and does not need to be populated before archiving an item. However, once set and the item archived, an error will occur if an attempt is made to change the value.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to change the value of this property after the item has been archived.

Example [C#] [in] item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000EVSite"; IContent content = item.Content; content.Title = "New title"; content.Author = "Charles Dickens" content.FileExtension = "msg"; content.OriginalLocation = "Inbox"; content.Data = "C:\\temp\\test.msg"; item.Insert(); [out] IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";

Content Management API ArchiveMetaData object

item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ITEM_PROPERTIES); IContent cont = item.Content; string author = content.Author;

ArchiveMetaData object This object implements the following interfaces: ■

IArchiveMetaData IID is {4A0AAD67-882B-4fd6-A76C-4F7B0864F5D6}

■

IArchiveMetaData2 IID is {5C6882BD-24BE-4C32-87EF-C3701D949BAA}

The interface is accessed using the ArchiveMetaData property of IItem, and provides calling applications with a set of properties that describe how the Item is archived. IArchiveMetaData2 provides additional properties for determining the location of an item, the Index Sequence Number (ISN) of an item and a read/write version of the ArchivedDate property.

Syntax interface IArchiveMetaData : IDispatch interface IArchiveMetaData2 : IArchiveMetaData

Member summary Table 4-30

IArchiveMetaData properties

Property

Read/Write

Description

RetentionCategory

Read/Write

This mandatory property contains the name or Id of the retention category assigned to the item. Typical category is "Business." for example.

ComplianceDevice

Read only

This property will be set to TRUE if the item is stored on a compliance device on which retention periods can be set.

225

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.

ArchivedDate

Read only

This property contains the UTC date and time that the item was originally stored into the archive.

ComplianceData

Read only

This property returns a valid pointer to an instance of the IComplianceData interface that allows the caller to set compliance values for the archived item.

SavesetSize

Read only

This property contains the saveset size (that is, the final size of the archived item as stored on disk) rounded to the nearest KB.

RetentionExpires

Read only

This property that contains the UTC date and time that the item will be able to be deleted from the archive.

IndexData

Read only

Pointer to a SimpleIndexMetadata object. ISimpleIndexMetadata methods and properties enable the calling application to retrieve the index properties of an archived item, or add custom index properties to an item as it is archived. The Search API can be used to find items with specific index data.

IsItemSecured

Read only

Property that indicates that is it safe to delete the original item from the source store. If the original item is deleted before the archive item is secured, then the item may not be restored as part of a disaster recovery of the Enterprise Vault server.

CustomIdentifier

Read/write

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

Content Management API ArchiveMetaData object

Table 4-30

IArchiveMetaData properties (continued)

Property

Read/Write

Description

CustomQualifier

Read/write

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

CustomProperties

Read/write

This property can be used to hold proprietary information about the stored item.

Table 4-31

IArchiveMetaData method

Method

Description

Update

Used to apply ComplianceData changes to a stored item.

Table 4-32

IArchiveMetaData2 properties

Property

Read/Write

Description

CurrentLocation

Read/write

Specifies the archive folder path to the current location of the item in the archive. The property is only intended for use with structured archives.

CurrentFolderId

Read/write

The ID of the current archive folder for the item. The property is only intended for use with structured archives.

SequenceNum

Read only

The Index Sequence Number (ISN) of the archived item.

ArchivedDate

Read/write

The UTC date and time that the item was originally stored in the archive.

Remarks Version information IArchiveMetaData2 interface requires Enterprise Vault 8.0.

227

228

Content Management API IArchiveMetaData :: RetentionCategory

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData;

IArchiveMetaData :: RetentionCategory This property contains the name or Id of the retention category assigned to the item. The property is read/write.

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR containing the current value of this property.

[in] BSTR newVal

New value to set this property to.

Remarks An example of this would be "Business" or any other retention category created using the Enterprise Vault Administrator Console. The retention category Id may be specified as an alternative. The Retention API can be used to discover or create retention categories. See “About Retention API” on page 562. Currently it is not possible to modify this property using the Content Management API after the item has been archived.

Content Management API IArchiveMetaData :: ComplianceDevice

Return value S_OK

Success.

S_FALSE

Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory Service is not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; string retCat = amd.RetentionCategory;

IArchiveMetaData :: ComplianceDevice This property indicates whether the item is stored on a compliance device on which retention periods can be set. The property is read only.

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

229

230

Content Management API IArchiveMetaData :: OverrideOnHoldRetCat

Parameters [out, retval] VARIANT_BOOL* pVal

Pointer to a VARIANT_BOOL which will contain the current value of this property

Remarks A value of true is returned if this item is on a compliance device.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; bool compDevice = amd.ComplianceDevice; if (conpDevice == true) { //do something

IArchiveMetaData :: OverrideOnHoldRetCat This property enables deletion of an item even if the retention category on-hold flag is enabled. The property is read/write.

Syntax HRESULT OverrideOnHoldRetCat([out, retval] VARIANT_BOOL* pVal); HRESULT OverrideOnHoldRetCat([in] VARIANT_BOOL newVal);

Content Management API IArchiveMetaData :: OverrideOnHoldRetCat

Parameters [out, retval] VARIANT_BOOL* pVal

Pointer to an VARIANT_BOOL which will contain the current value of this property

[in] VARIANT_BOOL newVal

VARIANT_BOOL containing the value to be set.

Remarks This property is set to ‘true’ if the item can be deleted even if the retention category on-hold flag is set. Once an item has been archived this property cannot be changed.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt was made to modify this property after the item had been stored in an archive.

Example [in] item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000EVSite"; IContent content = item.Content; content.Title = "New title"; content.FileExtension = "msg"; content.OriginalLocation = "Inbox"; content.Data = "C:\\temp\\test.msg"; IArchiveMetaData amd = item.ArchiveMetaData; amd.OverrideOnHoldRetCat = true; item.Insert(); [out] IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";

231

232

Content Management API IArchiveMetaData :: ArchivedDate

item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; bool override = amd. OverrideOnHoldRetCat; if (override == true) { //do something

IArchiveMetaData :: ArchivedDate This property contains the UTC date and time that the item was originally stored in the archive. The property is read only.

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

Parameters [out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the archived date of this item

Remarks This property is optional.

Version information At Enterprise Vault 8.0, this property becomes a read/write property. See “IArchiveMetaData2 :: ArchivedDate” on page 255.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

Content Management API IArchiveMetaData :: ComplianceData

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; object obj = amd.ArchivedDate; DateTime dt = (DateTime) obj;

IArchiveMetaData :: ComplianceData This property returns a valid pointer to an instance of the IComplianceDataInterface that allows the caller to set and view compliance values for the archived item. The property is read only.

Syntax HRESULT ComplianceData([out, retval] IComplianceData** pVal);

Parameters [out, retval] IComplianceData** pVal

Pointer to a valid IComplianceData pointer.

Remarks Although this property itself is read-only, its own properties allow compliance data to be added/modified. The IComplianceData interface enables compliance metadata to be set on an item in an archive. See “ComplianceData object” on page 281.

Return value S_OK

Success.

233

234

Content Management API IArchiveMetaData :: SavesetSize

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; IComplianceData compData = amd.ComplianceData; EV_STG_API_CP_UNITS evUnits = compData.Units; object obj = compData.Value; ulong val = (ulong)obj;

IArchiveMetaData :: SavesetSize This property holds the size of the archived item saveset, rounded to the nearest KB. The property is read/write.

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

Parameters [out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the current value of the property

Remarks This property is only available after an item has been archived. The VARIANT type of this property should be vt = VT_UI4. Although it is marked as read/write, this property cannot be modified on an item that has already been archived.

Content Management API IArchiveMetaData :: RetentionExpires

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to modify this property after it has been stored in an archive.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; object obj = amd.SavesetSize; ulong size = (ulong)obj;

IArchiveMetaData :: RetentionExpires This property contains the UTC date and time when the item can be deleted from a compliance storage device. The property is read only.

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

Parameters [out,retval] VARIANT* pVal

Pointer to a VARIANT that will contain the current value.

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

235

236

Content Management API IArchiveMetaData :: IndexData

See “EV_STG_API_ITEM_DETAIL enumeration” on page 83. If the item is stored on a compliance device, then the property value is the UTC date and time when the item can be deleted from the device. If the storage device is not a compliance device, then then the property value is 30/12/1899 00:00:00, which is equivalent to an Automation date of 0. The VARTYPE of the variant should be vt = VT_DATE.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_COMPLIANCE_DATA))); IArchiveMetaData amd = item.ArchiveMetaData; object obj

= amd.RetentionExpires;

DateTime dt = (DateTime)obj;

IArchiveMetaData :: IndexData This property returns a pointer to a SimpleIndexMetadata object, which allows the calling application to enumerate system and custom index properties for the current item, and add custom index properties when the item is archived. The property is read only.

Syntax HRESULT IndexData([out, retval] ISimpleIndexMetadata** pVal);

Content Management API IArchiveMetaData :: IsItemSecured

Parameters [out, retval] ISimpleIndexMetadata** pVal

Pointer to a SimpleIndexMetadata object.

Remarks The properties and methods of the ISimpleIndexMetadata interface can also be used to add custom index data to an item as it is archived. The additional index data is then available in the archive's index. The Search API can be used to find items with specific index properties and values. See “Adding custom index metadata” on page 72.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or an attempt has been made to access this property after the item has been archived.

Requirements Requires KVS.EnterpriseVault.Common.dll.

Example IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData;

See also ■

See “IItem :: Get” on page 194.

■

See “SimpleIndexMetadata object” on page 256.

IArchiveMetaData :: IsItemSecured This property indicates that is it safe to delete the original item from the source store.

237

238

Content Management API IArchiveMetaData :: IsItemSecured

The property is read only.

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

Parameters [out, retval] VARIANT_BOOL* pVal

Pointer to a VARIANT_BOOL which contains the current value of this property

Remarks If the original item is deleted before the archive item is secured, then the item may not be restored as part of a disaster recovery of the Enterprise Vault server. The meaning of "secured" depends upon the storage device; it may mean that the item has been backed-up, or that the storage device has replicated the item to a duplicate device.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)(EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) IArchiveMetaData amd = item.ArchiveMetaData; bool isSecured = amd.IsItemSecured; if (isSecured == true) { //safe to delete original item from the source

Content Management API IIArchiveMetaData :: CustomIdentifier

IIArchiveMetaData :: CustomIdentifier This property, together with the CustomQualifier property, can be used to provide proprietary identity information for the item. For example, this property could be used to hold the source store's identifier for the original item. The property is read/write.

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

Parameters [in] BSTR newVal

New value to set for this property.

[out, retval] BSTR* pVal

Pointer to a BSTR containing the current value of this property.

Remarks The maximum length of this property is 255 characters. This property is used in conjunction with the CustomQualifier property, which defaults to zero. It is possible to duplicate values using the CustomIdentifier/CustomQualifier properties. To ensure uniqueness, the CustomIdentifier value should use an application namespace, for example a GUID, as a prefix to the application identifier. For example, application GUID.application Id. As FSA and SharePoint Archiving use this property to hold information for restoring items, the property value should not be changed for items archived using FSA or SharePoint Archiving.

Return value S_OK

Success.

S_FALSE

Success. The default value (NULL) is returned.

239

240

Content Management API IIArchiveMetaData :: CustomQualifier

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or either an attempt has been made to modify this property after it has been stored in an archive, or the value exceeds 255 characters.

Example This VBScript example shows how CustomIdentifier, CustomQualifier and CustomProperties can be set. const CUSTOM_PROPERTIES = "" const CUSTOM_ID = "AcmeWidgetId-00002" const CUSTOM_QUALIFIER = 1 Dim oItem oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_ID oItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES oItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER

IIArchiveMetaData :: CustomQualifier This property, together with the CustomIdentifier property, can be used to provide proprietary identity information for the item. For example, if different versions of a document are archived, this property could hold the document version information. The property is read/write.

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

Parameters [in] LONG newVal

New value to set for this property.

Content Management API IIArchiveMetaData :: CustomQualifier

[out, retval] LONG* pVal

Pointer to a LONG containing the current value of this property.

Remarks This property is used in conjunction with the CustomIdentifier property. The property can only be set after the CustomIdentifier property has been set. If a CustomIdentifier has been set this property defaults to zero. As FSA and SharePoint Archiving use this property to hold information for restoring items, the property value should not be changed for items archived using FSA or SharePoint Archiving.

Return value S_OK

Success

S_FALSE

Success. The default value (0) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or either an attempt has been made to modify this property after it has been stored in an archive, or the CustomIdentifier property has not been set.

Example This VBScript example shows how CustomIdentifier, CustomQualifier and CustomProperties can be set. const CUSTOM_PROPERTIES = "" const CUSTOM_ID = "AcmeWidgetId-00002" const CUSTOM_QUALIFIER = 1 Dim oItem oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_ID oItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES oItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER

241

242

Content Management API IIArchiveMetaData :: CustomProperties

IIArchiveMetaData :: CustomProperties This property can be used to hold proprietary information about the stored item. The property is read/write.

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

Parameters [in] BSTR newVal

New value to set for this property.

[out, retval] BSTR* pVal

Pointer to a BSTR containing the current value of this property.

Remarks The maximum length of this property is 2500 characters. As FSA and SharePoint Archiving use this property to hold information for restoring items, the property value should not be changed for items archived using FSA or SharePoint Archiving.

Return value S_OK

Success

S_FALSE

Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or either an attempt has been made to modify this property after it has been stored in an archive, or the value exceeds 2500 characters.

Example This VBScript example shows how CustomIdentifier, CustomQualifier and CustomProperties can be set.

Content Management API IArchiveMetaData :: Update

const CUSTOM_PROPERTIES = "" const CUSTOM_ID = "AcmeWidgetId-00002" const CUSTOM_QUALIFIER = 1 Dim oItem oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_ID oItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER oItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES

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. Currently the Update method cannot be used to update any other archive metadata properties.

Syntax HRESULT Update(void)

Remarks The ArchiveId and Id properties must be set prior to calling the Update method. The operation will only be performed if the compliance device allows it. If this is not the case, a bad HRESULT will be returned, indicating the cause of the failure. Note the following when extending the compliance period on an item: ■

You cannot change the compliance period if the item is stored on a device that has no compliance period or does not support extending the compliance period.

■

The new retention period must be longer than the original retention period.

■

You can only extend the retention period of the retention category assigned to the item; you cannot assign a different retention category.

■

You cannot remove the compliance period completely by setting values to "NONE".

■

The only values that can be changed currently are the compliance unit and value properties.

See “ComplianceData object” on page 281.

243

244

Content Management API IArchiveMetaData :: Update

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

A NULL pointer has been passed in, or either the archive or item Id has not been set, or there is an error with the retention category, or an attempt has been made to change it.

CONTENTMANAGEMENTAPI_E_INVALID_DEVICE

The storage device is not a compliance device.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

CONTENTMANAGEMENTAPI_E_NO_ACCESS

The caller does not have write access to the target archive or archive folder.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_COMPLIANCE_DATA))); IArchiveMetaData amd = item.ArchiveMetaData;

Content Management API IArchiveMetaData2 :: CurrentLocation

IComplianceData compData = amd.ComplianceData; compData.Units = EV_STG_API_CP. CP_UNITS_MONTHS; compData.Value = 18; amd.Update();

IArchiveMetaData2 :: CurrentLocation This property specifies the path of the archive folder in which the item is currently stored, or is to be stored when performing insert, copy or move item operations. This property is only intended for use with structured archives, that is, archives that contain folders. The property is read/write.

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

Parameters [in] BSTR newVal

Folder path to be set as the item's current location in the archive.

[out, retval] BSTR* pVal

Archive folder path set as the item's current location.

Remarks The Items collection object can be used to populate this property automatically. The property value is automatically populated by any of the following methods: ■

Insert

■

MoveTo

■

CopyTo

The folder path specifies the archive folder path relative to the root, or default, archive folder. The following examples illustrate the default root archive folder path used by the CurrentLocation property for the different types of archives: ■

Mailbox archives.

245

246

Content Management API IArchiveMetaData2 :: CurrentLocation

The CurrentLocation property value does not contain any folder path elements for the default root archive folder. The example value "Inbox\Accounts" represents the location of an item in the folder "Accounts", which is subfolder of "Inbox" archive folder. ■

Public Folder archives. The default root archive folder path in the CurrentLocation property value represents the location of the Exchange Public Folder archiving target. For example, if the folder path for an Exchange Public Folder archiving target is "EXCHSVR\Sales\Documents", and the value of the CurrentLocation property is "EXCHSVR\Sales\Documents\FolderA", then the item is located in the folder "FolderA", which is subfolder of the root archive folder for the Public Folder archiving target.

■

FSA archives. The default root archive folder path in the CurrentLocation property value represents the location of the FSA volume archiving target. For example, if the folder path for an FSA volume archiving target is "\\FileSVR1.Example.COM\FSA Volume\5", and the value of the CurrentLocation property is "\\FileSVR1.Example.COM\FSA Volume\5\NewFolder", then the item is located in the folder "NewFolder", which is subfolder of the root archive folder for the FSA volume archiving target.

■

SharePoint archives. The default root archive folder path in the CurrentLocation property value represents the URL of the SharePoint site collection archiving target. For example, if the URL for a SharePoint site collection archiving target is "http://sharepoint/sites/marketing", and the value of the CurrentLocation property is "http://sharepoint/sites/marketing/UK", then the item is located in the folder "UK", which is subfolder of the root archive folder for the SharePoint site collection target. Note that the syntax rules applied to SharePoint archive folder paths differ from those applied to folder paths in other types of archive.

The following syntax rules apply when retrieving or setting the CurrentLocation property value for archives other than SharePoint archives; ■

The backslash character (‘\’) is treated as the folder path subfolder separator character.

■

Double backslash (‘\\’) is used for preserving a backslash character in the folder path string.

■

Leading backslash characters will be ignored.

Content Management API IArchiveMetaData2 :: CurrentLocation

If the CurrentLocation property is specified for a flat archive (for example, shared or journal archives, which do not contain folders), then the property value returned is an empty string. You can use the IArchive2::HasFolders property to determine if the archive is flat or has a folder structure.

Which properties determine the current archive folder For item insert, copy or move operations, each of the following properties can be used to set the archive folder: ■

IArchiveMetaData2::CurrentLocation

■

IArchiveMetaData2:: CurrentFolderId

■

IContent::OriginalLocation

The following conditions should be noted: ■

CurrentFolderId and CurrentLocation properties are only intended for use with archives that contain folders.

■

CurrentFolderId and CurrentLocation are mutually exclusive.

■

CurrentFolderId and CurrentLocation are optional.

■

When copying or moving an item, then the destination archive folder is defined by IArchiveMetaData2::CurrentLocation (if the source archive contains a folder structure), or IContent::OriginalLocation (if the source archive is flat). If neither of these properties is specified, then the root folder of the archive is used. For insert, copy or move operations, if the value of ArchiveId is an archive folder ID, then the ArchiveId property can be used instead of CurrentFolderId or CurrentLocation to define the archive folder for the item.

■

If the folder identified by CurrentLocation (or IContent::OriginalLocation, when defaulting) has not yet been created, it is created automatically, together with any missing parent folders. The caller must have write access on the destination archive in order to create new folders. When creating new folders, folder permissions are inherited from the parent folder.

■

If IContent::OriginalLocation property is omitted, the value is populated with the path of the item's archive folder (insert operation), or the path of the item's archive folder in the source archive (copy or move operation).

Methods to enumerate, create, delete (if empty) and update archive folders are not currently available. Also, caller applications cannot manage folder level permissions using the Content Management API.

247

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, move and copy operations

ArchiveId Property

CurrentFolderId CurrentLocation OriginalLocation Archived to Property Property Property folder

Saveset OriginalLocation1

Archive Id

Not specified

Not specified

Not specified

Root folder

"" (i.e. Empty string)

Archive Id

Not specified

Not specified

Specified

Folder matching Value of CurrentLocation OriginalLocation or property OriginalLocation property (Folder created as necessary - viz current refile behaviour)

Archive Id

Not specified

Specified

Not specified

Folder matching CurrentLocation property (Folder created as necessary)

Value of CurrentLocation property

Archive Id

Not specified

Specified

Specified

Folder matching CurrentLocation property (Folder created as necessary)

Value of OriginalLocation property

Archive ID

Specified

Not specified

Not specified

Specified folder.

Path of the specified CurrentFolderId from the Directory

(It must be a folder in the archive)

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. Value of (It must be a OriginalLocation folder within the property archive)

Archive ID

Specified

Specified

Irrelevant

Not supported; error with invalid arguments2

Archive folder ID

Not specified

Not specified

Not specified

Folder specified in ArchiveId property

Path of specified Archive folder ID from the Directory

Archive folder ID

Not specified

Not specified

Specified

Folder specified in ArchiveId property

Value of OriginalLocation property

Archive folder ID

Not specified

Specified

Not specified

Folder matching CurrentLocation property.

Value of CurrentLocation property

(Folder created as necessary) Archive folder ID

Not specified

Specified

Specified

Folder matching CurrentLocation property.

Value of OriginalLocation property

(Folder created as necessary) Archive folder ID

Specified

Not specified

Not specified

Specified folder. (It must be a folder in the archive)

Archive folder ID

Specified

Not specified

Specified

Specified folder. (It must be a folder in the archive)

Path of the specified CurrentFolderId from the Directory Value of OriginalLocation property

249

250

Content Management API IArchiveMetaData2 :: CurrentLocation

Determining the target archive folder for insert, 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; error with invalid arguments 2

1.(CopyTo and MoveTo) If OriginalLocation is not specified, then it is copied from the source item saveset value. 2.Allowed if the archive folder ID associated with the specified CurrentLocation matches the specified CurrentFolderId value.

Return value S_OK

Success.

S_FALSE

Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or newVal is not a syntactically valid folder path.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

Example [C++] IItem* pItem = NULL; pCmAPI->get_Item(&pItem); //

Identify ArchiveID of archive in which item is stored

Content Management API IArchiveMetaData2 :: CurrentFolderId

CComBSTR ArchiveId (L"181E669473B52E64384C9A7D9EACA0E7E1110000evsite"); pItem->put_ArchiveId(ArchiveId); // Identify Id of stored item CComBSTR ItemId (L" 161000000000000~200501051649270000~0~9039 eb282e3d4083b79f3298dc8a1e60") pItem->put_Id(ItemId); pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA ); IArchiveMetaDatat* pAMD = NULL; pItem->get_ArchiveMetaData(&pAMD); //Fetch the item's current archive folder path location CComBSTR CurrentLocation; CComQIPtr pAMD2(pAMD); pAMD2->get_CurrentLocation(&CurrentLocation);

IArchiveMetaData2 :: CurrentFolderId This property specifies the ID of the archive folder in which the item is currently stored, or is to be stored when performing insert, copy or move item operations. This property is only intended for use with structured archives, that is, archives that contain folders. The property is read/write.

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

Parameters [in] BSTR newVal

The ID of the archive folder to set as current folder for the item.

[out, retval] BSTR* pVal

The ID of the item's current archive folder.

251

252

Content Management API IArchiveMetaData2 :: CurrentFolderId

Remarks The Items collection object populates this property automatically. The property value is automatically populated by any of the following methods: ■

IItem::Insert

■

IItem::MoveTo

■

IItem::CopyTo

For item insert, copy or move operations on structured archives, each of the following properties can define the destination archive folder: ■

IArchiveMetaData2::CurrentLocation

■

IArchiveMetaData2:: CurrentFolderId

■

IContent::OriginalLocation

See “IArchiveMetaData2 :: CurrentLocation” on page 245. If the CurrentFolderId property is specified for a flat archive (for example, shared or journal archives, which do not contain folders), then the property value is populated with the archive Id value after an Item property retrieval operation. You can use the IArchive2::HasFolders property to determine if the archive is flat or has a folder structure.

Return value S_OK

Success.

S_FALSE

Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or newVal is an not a valid archive folder Id.

Example [C++] IItem* pItem = NULL; pCmAPI->get_Item(&pItem); // Identify ArchiveID of archive in which item is stored CComBSTR ArchiveId

Content Management API IArchiveMetaData2 :: SequenceNum

(L"181E669473B52E64384C9A7D9EACA0E7E1110000evsite"); pItem->put_ArchiveId(ArchiveId); // Identify Id of stored item CComBSTR ItemId (L" 161000000000000~200501051649270000~0~9039 eb282e3d4083b79f3298dc8a1e60") pItem->put_Id(ItemId); pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA ); IArchiveMetaDatat* pAMD = NULL; pItem->get_ArchiveMetaData(&pAMD); //Fetch the item's current archive folder ID CComBSTR CurrentFolderId; CComQIPtr pAMD2(pAMD); pAMD2->get_CurrentFolderId(&CurrentFolderId);

IArchiveMetaData2 :: SequenceNum This property specifies the Index Sequence Number of the archived item. The property is read only.

Syntax HRESULT SequenceNum ([out, retval] ULONGLONG* pVal)

Parameters [out, retval] ULONGLONG* pVal

The Index Sequence Number (ISN) of the archived item.

Remarks This property uniquely identifies the item in the archive. It can be used to identify the start Index Sequence Number when enumerating collections of archived items using the Items collection object. See “IItems :: StartSequenceNum” on page 169. The Items collection object populatesthis property automatically. This is useful for bulk moving or copying items.

253

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, as items may have expired or been deleted.

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example This example shows how to use the IArchiveMetaData2 interface to fetch the SequenceNUm property. [C#] Item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; Item.Id = "200808070000000~200808070940280000~Z~BFA0C1B1FAB1468DB82 2E2473B4AAB05" Item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA); // Fetch the item's sequence no property // IArchiveMetaData2 IAMD2 = (IArchiveMetaData2)EVItem. ArchiveMetaData; ulong SeqNo = EVIAMD2.SequenceNum;

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. The property is read/write.

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

Parameters [in] VARIANT newVal

The required UTC date and time to be set for this item

[out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the archived date of this item

Remarks Setting this property is optional. Typically it is only set to retain the archived date when copying or moving items. Note: Setting the archived date can affect the item's retention period. To specify an ArchivedDate when storing an item, set the ArchivedDate property value before calling the Insert method. When copying or moving an item, the default action is to retain the item's archived date. To reset the achived date to the current date time, simply set a null value on the destination ArchiveMetadata object. See “IItem :: CopyOptions” on page 187.

Return value S_OK

Success.

S_FALSE

Success. The default value (0) is returned.

255

256

Content Management API SimpleIndexMetadata object

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

Supplied Variant type not VT_NULL or VT_DATE, or an attempt was made to modify this property after the item had been stored in an archive, or pVal is NULL.

Example IItem itemSrc = cmAPI.Item; IItem itemDst = cmAPI.Item; itemSrc.ArchiveId ="181E669473B52E64384C9A7D9EACA0E7E1110000ev site"; itemSrc.Id ="334880000000000~200707251102240000~0~D3962A35951E4B03 AE9CFB68AFE1218"; itemDst.ArchiveMetaData.RetentionCategory = "Business"; itemDst.ArchiveMetaData.ComplianceData.SetBy = EV_STG_API_CP_SETBY.SETBY_RETCAT; IArchiveMetaData2 amd = (IArchiveMetaData2)itemDest.ArchiveMetaData; amd.ArchivedDate = DateTime.Now(); itemSrc.CopyTo(itemDst);

SimpleIndexMetadata object This object implements the following interface: ■

ISimpleIndexMetadata

A SimpleIndexMetadata object is a collection of SimpleIndexProperty objects. You can use the ISimpleIndexMetadata methods and properties to add new custom index properties before an item is archived, and to enumerate the individual properties that belong to an item.

Syntax interface ISimpleIndexMetadata : IDispatch

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.

Table 4-35

ISimpleIndexMetadata methods

Method

Description

Count

Gives the number of custom index metadata properties for the current item.

Add

Adds a value for a custom index property.

Clear

Clears all properties from the SimpleIndexMetadata object for the current item.

ToXML

Returns the metadata in XML format.

FromXML

Loads a set of properties that have previously been defined and stored using the ToXML method.

ToLocalTime

Converts a UTC time to local system time.

ToUTCTime

Converts a local system time to UTC time.

Remarks The type of properties returned in the collection can be controlled using the enumeration, EV_STG_API_ITEM_DETAIL, on the Get method of the IItem interface.

Examples [C#]

257

258

Content Management API SimpleIndexMetadata object

IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData;

The following VBScript excerpt gives an example of how metadata can be read from the instance returned by Content Management API: [VBScript] [C#] ‘ Get the Index Metadata from the retrieved item Set IMData = oItem.ArchiveMetaData.IndexData if (IMData.Count() = 0) then WScript.Echo "No properties loaded!", vbOKOnly + vbExclamation, "Index Metadata" Err.Clear else ‘Use local system date/times IMData.DateTimesUTC = false ‘ Loop through the properties displaying the details of each Dim idxprop for each idxprop in IMData Dim propInfo Dim pVal propInfo = "Set: " + idxprop.Set + vbCrLf + "Name: " + idxprop.Name propInfo = propInfo + vbCrlf + "Searchable: " + CStr(idxprop.Searchable) propInfo = propInfo + vbCrlf + "Retrievable: " + CStr(idxprop.Retrievable) pVal = idxprop.Value propInfo = propInfo + vbCrLf + "Value (" + TypeName(pVal) + "): " + CStr(pVal) WScript.Echo propInfo, vbOKOnly, "Index Metadata Properties List" next if (Err.number 0) then WScript.Echo "Enumerating failed!" + vbCrLf + "Reason: " + Hex(Err.number) + vbCrLf + "Description: " + Err.Description, vbOKOnly + vbExclamation, "Index Metadata" Err.Clear end if end if

Content Management API ISimpleIndexMetadata :: _NewEnum

Requirements Implemented in KVS.EnterpriseVault.Common.dll.

See also ■

See “SimpleIndexProperty object” on page 269.

■

See “IItem :: Get” on page 194.

■

See “Adding custom index metadata” on page 72.

ISimpleIndexMetadata :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the SimpleIndexMetadata collection object. This property is hidden in Visual Basic Scripting Edition (VBScript). The property is read only.

Syntax HRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters [out,retval] IUnknown** enumerator

Returned reference to the IUnknown interface of the object.

Remarks This property is a standard property used to support enumerating collections, it is automatically used internally when you use the For Each construct in C#, or VBScript. A collection of SimpleIndexProperty objects is returned.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer passed to receive property value.

259

260

Content Management API ISimpleIndexMetadata :: DateTimesUTC

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set; string name = ip.Name; object val = ip.Value; bool searchable = ip.Searchable; bool retrievable = ip.Retrievable; //do something with the values obtained }

ISimpleIndexMetadata :: DateTimesUTC This boolean property sets or retrieves whether the date and time properties are input and output in UTC or local system time.

Syntax HRESULT DateTimesUTC([out, retval] VARIANT_BOOL* pRetVal); HRESULT DateTimesUTC([in] VARIANT_BOOL pRetVal);

Parameters [out, retval] VARIANT_BOOL* pRetVal

Whether time property values are UTC times or as local system times.

[in] VARIANT_BOOL pRetVal

Whether time property values are UTC times or as local system times.

Content Management API ISimpleIndexMetadata :: Count

Remarks By default, items are always archived using UTC time.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pRetVal is NULL.

Example ‘Use local system date/times IMData.DateTimesUTC = false

ISimpleIndexMetadata :: Count This method gives the number of custom index metadata properties for the current item.

Syntax HRESULT Count([out, retval] long* pRetVal);

Parameters [out, retval] long* pRetVal

Number of custom index metadata properties.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pRetVal is NULL.

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

261

262

Content Management API ISimpleIndexMetadata :: Add

IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; if (simple.Count> 0) { //do something

ISimpleIndexMetadata :: Add This method is used to add a custom index property to an item before it is archived. The property is then available in the index document for the item. The Search API can be used to search for specific index data.

Syntax HRESULT Add [in] BSTR propertySet, [in] BSTR propertyName, [in] VARIANT propertyValue, [in] VARIANT_BOOL propertySearchable, [in] VARIANT_BOOL propertyRetrievable);

Parameters [in] BSTR propertySet

Name of the property set to which the property belongs, or is to be added. If no property set is specified, the property is added to the default (global) property set.

[in] BSTR propertyName

Name of the property.

[in] VARIANT propertyValue

Property value. A Variant containing a value of any of the supported types listed in Table 4-36.

Content Management API ISimpleIndexMetadata :: Add

[in] VARIANT_BOOL propertySearchable

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

[in] VARIANT_BOOL

propertyRetrievable

Defines whether the property values can be requested in search results. Setting the value to true means that property information can be retrieved and displayed later with the item in search results. The default value is false.

Table 4-36

Supported types for propertyValue

Value type

Variant type

Note

String

VT_BSTR

dateTime

VT_DATE

Limited to the UTC date range 1st January 1970 to 1st January 2038

Integer

VT_UI1, VT_UI2, VT_UI4, VT_UI8, VT_I1, VT_I2, VT_I4, VT_I8, VT_INT, VT_UINT, or VT_DECIMAL

Limited to the range 0 to 4,294,967,294

Remarks Custom index data can only be added when the item is inserted, copied or moved. It is not possible to update custom index data for an archived item. The method can be called repeatedly to add multiple properties or to add multiple values to the same property. When you use Add to add a property to the index, the property will be added to the property set specified by the propertySet parameter. If a property set is specified that does not exist, then the property set will be created and the property and value will be added to that new set. It is good practice to use a named property set for properties added by an application in order to avoid name clashes with other custom additions. Suitable

263

264

Content Management API ISimpleIndexMetadata :: Add

names would be your company name or the application name. The following property set names are reserved: ■

Vault

■

EnterpriseVault

■

Any property set name starting with EV

■

KVS

■

Veritas

■

Symantec

Hints and tips on adding custom index properties are provided in the introduction to the Content Management API. See “Adding custom index metadata” on page 72.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

propertySet is NULL, or propertyName is NULL or an empty string, or propertyValue is NULL or an invalid type or is an invalid value, for example out of supported range.

Example item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = item.Content; content.Title = "New title"; content.FileExtension = "msg"; content.OriginalLocation = "Inbox"; content.Data = "C:\\temp\\test.msg"; IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; //add some custom index data simple.Add("My set", "My name", 32, true, true); item.Insert();

Content Management API ISimpleIndexMetadata :: Clear

ISimpleIndexMetadata :: Clear This method is used to clear all properties from the SimpleIndexMetadata object for the current item.

Syntax HRESULT Clear();

Return value S_OK

Success.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA) | ( EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; simple.Clear();

ISimpleIndexMetadata :: ToXML This method returns the metadata in XML format.

Syntax HRESULT ToXML( [in] VARIANT_BOOL formattedLayout, [out, retval] BSTR* pRetVal);

Parameters [in] VARIANT_BOOL formattedLayout

If true, the XML returned will be in human-readable format.

[out, retval] BSTR* pRetVal

An XML string is returned.

265

266

Content Management API ISimpleIndexMetadata :: ToXML

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pRetVal is NULL.

Examples The following code excerpt gives an example of how metadata can be added and returned as XML, using the ToXML method: Option Explicit ‘On Error Resume Next Dim ecmAPI Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI") Dim oItem set oItem = ecmAPI.Item oItem.ArchiveId = "137100ED24187DB43A884B0C0B8D3FF511110000EVServer" // populate the Data property from a file oItem.Content.Data = "c:\data file.doc" oItem.Content.Title = "function design document.doc" oItem.ArchiveMetaData.RetentionCategory = "Technical Documents" oItem.ArchiveMetaData.ComplianceData.SetBy = RetCat Dim IMData set IMData = oItem.ArchiveMetaData.IndexData IMData.Clear ‘ Use local date and time IMData.DateTimesUTC = false ‘ Add a property called Agent, with the string value, ‘ "EgApplication" to the default, global property set. This property ‘ is searchable and retrievable. IMData.Add vbNullString, "Agent", "EgApplication",true, true ‘ Add the following properties to the property set called "EgApp". IMData.Add "Egapp", "File", "EgFilename", false, true IMData.Add "EgApp", "TimeStamp", CDate("2006-10-23 12:00:00"), false, true ‘ return the property information as formatted XML WScript.Echo IMData.ToXML(true) oItem.Insert() // actually performs the insert ...

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. Figure 4-3

ToXML result

See also ■

See “ArchiveMetaData object” on page 225.

ISimpleIndexMetadata :: FromXML This method enables you to load a set of properties that have previously been defined and stored using the ToXML method.

Syntax HRESULT FromXML([in] BSTR xmlIndexMetadata);

Parameters [in] BSTR xmlIndexMetadata

The XML stream to input.

Remarks Use the Add method to add item specific values. The XML schema is not published, as the Add method should always be used to add metadata properties.

267

268

Content Management API ISimpleIndexMetadata :: ToLocalTime

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

xmlIndexMetadata supplied as NULL, or is invalid XML.

Example item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite"; IContent content = item.Content; content.Title = "New title"; content.FileExtension = "msg"; content.OriginalLocation = "Inbox"; content.Data = "C:\\temp\\test.msg"; IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; //add some custom index data from xml simple. FromXML(xmlData); //xmlData is a pre-populated string containing the xml item.Insert();

ISimpleIndexMetadata :: ToLocalTime This is a helper method to convert a UTC time to local system time.

Syntax HRESULT ToLocalTime( [in] DATE utcDateTime, [out, retval] DATE* pRetVal);

Parameters [in] DATE utcDateTime

The UTC date and time to convert.

[out, retval] DATE* pRetVal

The local date and time are returned.

Content Management API ISimpleIndexMetadata :: ToUTCTime

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pRetVal is NULL,or utcDateTime is not a syntactically valid UTC date time value.

ISimpleIndexMetadata :: ToUTCTime This is a helper method to convert a local system time to UTC date and time.

Syntax HRESULT ToUTCTime( [in] DATE localDateTime, [out, retval] DATE* pRetVal);

Parameters [in] DATE localDateTime

The local date and time to convert.

[out, retval] DATE* pRetVal

The local date and time are returned.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

pRetVal is NULL,or localDateTime is not a syntactically valid local date time value.

SimpleIndexProperty object The SimpleIndexProperty object implements the following interface: ■

ISimpleIndexProperty

269

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.

Name

Read only

Name of the property.

Value

Read only

Value assigned to the property.

Searchable

Read only

Whether the property is to be added to the item index.

Retrievable

Read only

Whether the property can be included in search results.

System

Read only

Whether the property is one that is indexed by default during the archiving process.

Remarks Properties added to the item index using the Add method of the ISimpleIndexMetadata interface are held as SimpleIndexProperty objects.

Example IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) {

ISimpleIndexProperty :: Set This property returns the property set name. The property is read only.

Content Management API ISimpleIndexProperty :: Set

Syntax HRESULT Set([out, retval] BSTR* value);

Parameters [out, retval] BSTR* value

Property set name.

Remarks If empty, the property is a member of the global property set.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer was passed to receive property value.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set; string name = ip.Name; object val = ip.Value; bool searchable = ip.Searchable; bool retrievable = ip.Retrievable; //do something with the values obtained }

271

272

Content Management API ISimpleIndexProperty :: Name

ISimpleIndexProperty :: Name This property returns the property name. The property is read only.

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

Parameters [out,retval] BSTR* value

Name of the property.

Remarks The name of a property can be a predefined name, such as IndexPropSUBJ, the numeric identification of an attachment (for example, 1.1), or a custom name. If the value is a formatted number (1, 1.1, 1.2 and so on), then the property refers to a message attachment, which may be a file or a message. In this case, the value is another instance of a SimpleIndexMetadata object, detailing the index properties of the attachment. If the property is a top-level message, then the Name is "1". The first attachment would be "1.1". The first attachment on a nested message would be "1.1.1". Figure 4-4 illustrates the naming convention for messages and attachments.

Content Management API ISimpleIndexProperty :: Name

Naming format for messages

Figure 4-4

Top-level message 1 Message Attachments

1.2

1.1

1.1.1

1.1.2

1.3

1.2.1

1.2.1.1

Each of the nested items has their own set of properties, which can be enumerated. The property, IndexPropANUM, also contains the numeric identity of a message attachment. The value of this property differs from the property Name. Figure 4-5 shows the values of IndexPropANUM for a message with an attached document and an attached message, which also has attached documents.

273

274

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, the COMR (content missing) property is returned in the index data. The value of this property indicates the reason for the missing content. See “Note 4” on page 610.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer was passed to receive property value.

Version information ■

Numeric identity of a message attachments in IndexPropANUM is available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 40.

■

Content missing reasons returned in the index data COMR property is available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 40.

Content Management API ISimpleIndexProperty :: Value

■

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

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL _CUSTOM_INDEX_METADATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set; string name = ip.Name; object val = ip.Value; bool searchable = ip.Searchable; bool retrievable = ip.Retrievable; //do something with the values obtained }

See also ■

See “System properties” on page 596.

ISimpleIndexProperty :: Value This property returns the property value. The property is read only.

Syntax HRESULT Value([out,retval] VARIANT* value);

275

276

Content Management API ISimpleIndexProperty :: Value

Parameters [out,retval] VARIANT* value

Table 4-38

Property value. A Variant containing a value of any of the supported types listed in Table 4-38.

Supported types for Value

Value type

Variant type

String

VT_BSTR

Datetime

VT_DATE

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

SimpleIndexMetadata object VT_UNKNOWN

Note

An ISimpleIndexProperty instance

Remarks If the Name property is a formatted number (1.1, 1.2 and so on), then the property refers to a message attachment, which may be a file or a message. In this case, the Value property is a SimpleIndexMetadata object, detailing the index properties of the attachment. 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.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer was passed to receive property value.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60";

Content Management API ISimpleIndexProperty :: Searchable

item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set; string name = ip.Name; object val = ip.Value; bool searchable = ip.Searchable; bool retrievable = ip.Retrievable; //do something with the values obtained }

ISimpleIndexProperty :: Searchable This property returns whether the property is indexed, and hence can be searched for using the Search API. The property is read only.

Syntax HRESULT Searchable([out,retval] VARIANT_BOOL* value);

Parameters [out,retval] VARIANT_BOOL* value

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer was passed to receive property value.

277

278

Content Management API ISimpleIndexProperty :: Retrievable

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_CUSTOM_INDEX_METADATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set; string name = ip.Name; object val = ip.Value; bool searchable = ip.Searchable; bool retrievable = ip.Retrievable; //do something with the values obtained }

See also ■

See “System properties” on page 596.

ISimpleIndexProperty :: Retrievable This property returns whether the property can be retrieved and displayed with search results in the search application. The property is read only.

Syntax HRESULT Retrievable([out,retval] VARIANT_BOOL* value);

Parameters [out,retval] VARIANT_BOOL* value

Content Management API ISimpleIndexProperty :: System

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer was passed to receive property value.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set; string name = ip.Name; object val = ip.Value; bool searchable = ip.Searchable; bool retrievable = ip.Retrievable; //do something with the values obtained }

See also ■

See “System properties” on page 596.

ISimpleIndexProperty :: System This property indicates that the property is an Enterprise Vault system property. See “System properties” on page 596. The property is read only.

279

280

Content Management API ISimpleIndexProperty :: System

Syntax HRESULT System([out,retval] VARIANT_BOOL* value);

Parameters [out,retval] VARIANT_BOOL* value

Remarks For custom properties that are added using Add, the value of System is always false.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer was passed to receive property value.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)((EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA) | (EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_CUSTOM_INDEX_METADATA) | (EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_SYSTEM_INDEXDATA))); IArchiveMetaData amd = item.ArchiveMetaData; ISimpleIndexMetadata simple = amd.IndexData; foreach (ISimpleIndexProperty ip in simple) { string set = ip.Set; string name = ip.Name; object val = ip.Value; bool searchable = ip.Searchable; bool retrievable = ip.Retrievable; bool isSystem = ip.System; //do something with the values obtained }

Content Management API ComplianceData object

281

See also ■

See “System properties” on page 596.

ComplianceData object This object implements the following interface: ■

IComplianceData

The IComplianceData interface is obtained by using the ComplianceData property of the IArchiveMetaData interface.

Syntax interface IComplianceData : IDispatch

Remarks The IComplianceData interface is for use only with compliance devices.

Member summary Table 4-39

IComplianceData properties

Property

Read/Write

Description

Value

Read/Write

Combined with the Units property specifies the duration of the compliance period.

Units

Read/Write

Specifies the compliance period units, for example, days, weeks, months, years.

SetBy

Write only

Defines where the compliance period is set; the ComplianceData object, the retention category, or not set.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; IComplianceData compData = amd.ComplianceData;

282

Content Management API IComplianceData :: Units

IComplianceData :: Units This property, combined with the Value property, specifies the duration of the compliance period. The property is read/write.

Syntax HRESULT Units([out, retval] EV_STG_API_CP_UNITS* pVal); HRESULT Units([in] EV_STG_API_CP_UNITS newVal);

Parameters [out, retval] EV_STG_API_CP_UNITS* pVal

Pointer an EV_STG_API_CP_UNITS enumerated type that contains the current value of this property

[in] EV_STG_API_CP_UNITS newVal

The new value to be set.

Remarks EV_STG_API_CP_UNITS indicates the units used in specifying the compliance period. See “EV_STG_API_CP_UNITS enumeration” on page 80.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or the value passed in to the property does not match one of the enumeration values.

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

Content Management API IComplianceData :: Value

DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; IComplianceData compData = amd.ComplianceData; EV_STG_API_CP_UNITS

evUnits = compData.Units;

object obj = compData.Value; ulong val = (ulong)obj;

IComplianceData :: Value This property, combined with the Units property, specifies the duration of the compliance period. The property is read/write.

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

Parameters [out, retval] VARIANT* pVal Pointer to a VARIANT that will hold the current value of the property [in] VARIANT newVal

VARIANT containing the new value to set

Remarks The VARTYPE of the VARIANT should be vt = VT_UI4 For example, for a compliance period of 6 days, Value = 6 and Units = CP_UNITS_DAYS

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or newVal is invalid.

283

284

Content Management API IComplianceData :: SetBy

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_ARCHIVE_METADATA); IArchiveMetaData amd = item.ArchiveMetaData; IComplianceData compData = amd.ComplianceData; EV_STG_API_CP_UNITS evUnits = compData.Units; object obj = compData.Value; ulong val = (ulong)obj;

IComplianceData :: SetBy This property indicates where the retention period was defined. The property is write only.

Syntax HRESULT SetBy([in] EV_STG_API_CP_SETBY newVal);

Parameters [in] EV_STG_API_CP_SETBY newVal

EV_STG_API_CP_SETBY containing the new value of the property

Remarks EV_STG_API_CP_SETBY indicates where the compliance retention period is set. See “EV_STG_API_CP_SETBY enumeration” on page 79. This property should only be used during a copy/move operation and should not be called once an item has added to the archive.

Return value S_OK

Success.

Content Management API Holds object

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

Invalid pointer passed to receive property value, or the value passed in does not conform to one of the enumeration type values.

Holds object This object implements the following interfaces: ■

IHolds

■

IHolds2

These interfaces enable calling applications to place holds on groups of items (to prevent them from being deleted), remove existing holds and list the holds that have been placed on items in a vault store. The IHolds2 interface inherits from IHolds, and provides the method ReleaseHolds2, which returns information in XML about the success or failure of removing holds on items in each vault store.

Syntax interface IHolds : IDispatch interface IHolds2 : IHolds

About Legal Hold Legal Hold is the ability to prevent deletion of documents that are relevant to a legal case; items that are placed on hold cannot be deleted by a user or by Enterprise Vault (using storage expiry). Legal Hold functionality is provided by the IHolds and IHold interfaces in the Content Management API. These interfaces allow Enterprise Vault Accelerator products and third-party applications to put items on hold, remove holds from items and enumerate all existing holds on an item. Existing functionality in Discovery Accelerator allows the administrator to put items on hold. Items can be placed on hold by specifying the following: ■

A Consumer ID, to identify the calling application.

■

A Group ID, to identify the group of items with a particular hold applied. The Group ID could, for example, identify the legal case.

■

Metadata, to provide additional information about the hold.

285

286

Content Management API Holds object

■

The list of items that the calling application wants to place on hold.

The metadata may be useful when there are several consumers of the Legal Hold API at the same time. For example, metadata could be used to say why one consumer has put the item on hold, and this information could then be accessed by other consumers. The metadata is in XML format, for example:

Using the IItem.Holds property, an application can enumerate all the holds which have been placed on an item; the API returns a list of holds (Hold IDs) on that item along with the metadata that was supplied when the item was put on hold. Holds may be removed from items in two ways: ■

By specifying the Consumer ID and the Group ID. This will remove all holds which have been placed on an item with the supplied Consumer ID and Group ID.

■

By supplying the Consumer ID and a list of Hold IDs of items from which the consumer wants to remove holds. This allows the consumer to remove holds from items in batches rather than a whole group at once.

Member summary Table 4-40

IHolds Properties

Property

Description

_NewEnum

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

Item

This property gives access to a particular instance of IHold in the collection using the index.

Count

This read only property returns the number of IHolds in the collection.

GroupId

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

ConsumerGUID

The ConsumerGUID is the unique identifier of the application calling the API.

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. The same metadata will be applied to each hold in the group.

Table 4-41

IHolds Methods

Method

Description

Add

Adds an IHold interface pointer to the collection.

PlaceHolds

Places a hold on each item in the collection.

ReleaseHolds

Releases a hold on each item in the collection.

Table 4-42

IHolds2 Method

Method

Description

ReleaseHolds2

Releases a hold on each item in the collection, and returns success or failure information, in XML format, for each vault store processed.

Version information IHolds2 interface requires Enterprise Vault 8.0 SP1.

See also See “Hold object” on page 300.

IHolds :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the IHolds collection object. This property is hidden in Visual Basic Scripting Edition (VBScript). The property is read only.

Syntax HRESULT _NewEnum([out,retval] IUnknown** enumerator);

287

288

Content Management API IHolds :: Item

Parameters [out,retval] IUnknown** enumerator

Returned reference to the IUnknown interface of the object.

Remarks This property is a standard property used to support enumerating collections, it is automatically used internally when you use the For Each construct in C#, or VBScript. A collection of IHold objects is returned.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

NULL pointer passed to receive property value.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA); IHolds holds = Item.Holds; foreach (IHold hold in holds) {

IHolds :: Item This property gives access to a particular hold in a collection. The property is read/write.

Syntax HRESULT Item([in] VARIANT index; HRESULT Item([out, retval] LPVARIANT pRetVal);

Content Management API IHolds :: Count

Parameters [in] VARIANT index

VARIANT holding the value of the index of the required hold.

[out, retval] LPVARIANT pRetVal

Pointer to a VARIANT that will return the current index value.

Remarks The VARTPYE of this property should be vt = VT_I4. Note that the index supplied to the property is 1-based not 0-based.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pRetVal pointer is NULL, or data type of variant was incorrect, or index is out of range.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA); IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { IHold hold = (IHold)holds.Item(i + 1);

IHolds :: Count This read only property returns the number of Holds in the collection. The property is read only.

289

290

Content Management API IHolds :: GroupId

Syntax HRESULT Count([out, retval] long* pRetVal);

Parameters [out, retval] long* pRetVal

Current number of holds in the collection.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pRetVal pointer is NULL.

Example IItem item = cmAPI.Item; item.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; item.Id = "200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; item.Get((int)EV_STG_API_ITEM_DETAIL. DETAIL_LEVEL_HOLD_DATA); IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { IHold hold = (IHold)holds.Item(i + 1);

IHolds :: GroupId This property is set to identify a group of holds placed at one time. This would typically be an identifier of a particular legal case, for example. The property is read/write.

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

Content Management API IHolds :: GroupId

Parameters [in] BSTR newVal

BSTR containing the new group Id.

[out,retval] BSTR* pVal

Pointer to a BSTR that will contain the current group Id.

Remarks The same GroupId used to place holds can also used to release all the holds in that group. A GroupId should consist of printable characters and should not contain any of the following characters: & ' "

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or newVal contains invalid characters, or one or more holds have already been placed for the current group.

Example IHolds holds = cmAPI.Holds; holds.GroupId = "Group 1"; holds.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; holds.MetaData = "Some metadata"; IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold); //add more hold's if necessary holds.PlaceHolds();

291

292

Content Management API IHolds :: ConsumerGUID

IHolds :: ConsumerGUID This property is the unique identifier of the application calling the API. The property is read only.

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

Parameters [in] BSTR newVal

BSTR containing any valid GUID value. Set by caller.

[out,retval] BSTR* pVal

Pointer to a BSTR containing the current GUID

Remarks The value should remain the same for all calls made to the ContentManagement API by the same calling application. It must be set before holds can be placed or released.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

PlaceHolds has been called so it is not possible to change this value or a valid CLSID could not be obtained from the BSTR passed in.

Example IHolds holds = cmAPI.Holds; holds.GroupId = "Group 1"; holds.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; holds.MetaData = "Some metadata"; IHold hold = cmAPI.Hold;

Content Management API IHolds :: Metadata

hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold); //add more hold's if necessary holds.PlaceHolds();

IHolds :: Metadata This property contains the metadata to be passed with the holds to the Enterprise Vault server. The property is read/write.

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

Parameters [in] BSTR newVal

BSTR containing the new MetaData value.

[out,retval] BSTR* pVal

Pointer to a BSTR that will contain the current value of the metadata.

Remarks The same metadata will be applied to each hold in the group.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

An attempt was made to modify this property once the PlaceHolds had been called.

293

294

Content Management API IHolds :: Add

Example IHolds holds = cmAPI.Holds; holds.GroupId = "Group 1"; holds.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; holds.MetaData = "Some metadata"; IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold); //add more hold's if necessary holds.PlaceHolds();

IHolds :: Add This method allows a client to add a new hold to the collection.

Syntax HRESULT Add([in] IHold* newHold);

Parameters .[in] IHold* newHold IHold interface pointer to add to the collection.

Remarks The IHold interface pointer must be obtained through the IContentManagementAPI property, Hold.

Return value S_OK

Success.

Content Management API IHolds :: PlaceHolds

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The Hold object has been used, or it has already been added with this Saveset Id, Transaction Id or Hold Id.

Example IHolds holds = cmAPI.Holds; holds.GroupId = "Group 1"; holds.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; holds.MetaData = "Some metadata"; IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold); //add more hold's if necessary holds.PlaceHolds();

IHolds :: PlaceHolds This function is used to actually place a hold on each item in the collection.

Syntax HRESULT PlaceHolds();

Remarks After the call has been placed, any errors in placing holds are reported in the Status property of the hold objects in the collection.

Return value S_OK

Success.

295

296

Content Management API IHolds :: ReleaseHolds

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

A NULL pointer has been passed to receive the property value, or the hold is already placed, the groupId is missing, or there is an error with the ConsumerGUID.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

Example IHolds holds = cmAPI.Holds; holds.GroupId = "Group 1"; holds.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; holds.MetaData = "Some metadata"; IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold); //add more hold's if necessary holds.PlaceHolds();

IHolds :: ReleaseHolds This function is used to release a hold on each item in the collection.

Syntax HRESULT ReleaseHolds();

Content Management API IHolds :: ReleaseHolds

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

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

297

298

Content Management API IHolds2 :: ReleaseHolds2

Example cmAPI.DirectoryDNSAlias = "SERVER1"; IHolds holds = cmAPI.Holds; holds.GroupId = "Group 1"; holds.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; holds.ReleaseHolds();

IHolds2 :: ReleaseHolds2 This method is similar to ReleaseHolds, in that it can be used to release a hold on each item in a collection, but this method also returns a summary status report, in XML, for each vault store in which items were processed.

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

Parameters [out,retval] BSTR* pVal Pointer to a BSTR that will contain the status report in XML.

Remarks The IContentManagementAPI :: DirectoryDNSAlias property should be set by the caller before releasing holds by GroupId. This is required to identify the Enterprise Vault server hosting the directory that will be used to enumerate the Enterprise Vault Storage service computers that the group of holds spans. When using a GroupId, if any of the holds in the group fail to be released, then the whole group is considered to have failed. Note that some holds may actually have been released, but the caller will need to repeat the release on the group as whole until it succeeds, after establishing the reason for failure and correcting it. When not using a GroupId, if the holds are spread over multiple vault stores, and any of the holds within a vault store fails to be released, all the holds in the vault store will also be marked as failed. Finally, when all holds in a group are eventually released, then to dispose of the group itself, you must also call ReleaseHolds2( ) specifying the GroupId as before.

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. In the XML, the vault store is identified by the Id field, and success or failure of the operation is indicated by the hr field (HRESULT). If the hold was released successfully on all affected items in a vault store, then the HRESULT returned for the vault store is 0. If the hold could not be released on some or all of the affected items in the vault store, then the hr field contains the error code value.

Version information ReleaseHolds2 method requires Enterprise Vault 8.0 SP1.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

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

Examples cmAPI.DirectoryDNSAlias = "SERVER1"; IHolds2 holds = (IHolds2)cmAPI.Holds; holds2.GroupId = "Group 1"; holds2.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; string xml holds2.ReleaseHolds2();

299

300

Content Management API Hold object

The following example shows XML returned by ReleaseHolds2. The HRESULT returned for the second vault store is not zero, indicating that the attempt to release the hold on items in this vault store failed.

Hold object This object implements the following interface: ■

IHold

The IHold interface contains properties that relate to a particular hold placed on a particular item. It is a collection of IHold interface pointers that are stored in the IHolds collection.

Syntax interface IHold : IDispatch

Member summary Table 4-43

IHold properties

Property

Description

ArchiveId

This property specifies the ArchiveID where the item to which this hold object refers is stored. This property must be set before a hold is placed or released.

ItemId

This property specifies the identifier of the item to which this hold object refers. This property must be set before a hold is placed.

Id

This property identifies the hold object. It is returned once a hold has been placed, and must be set before a hold can be released.

Status

This read only property returns the status of the hold after an attempt either to place or release a hold.

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.

ConsumerGUID

This read only property returns the unique identifier of the calling application that placed the hold.

GroupId

This read only property returns the identifier of the group of holds to which the hold belongs.

Remarks Being derived from IDispatch, this interface can be used by scripting languages.

Example IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold);

IHold :: ArchiveId This property specifies the ArchiveID of the archive where the item that this hold object refers to is stored. The property is read/write.

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the archive Id of the archive holding the item referred to by this hold.

[in] BSTR newVal

BSTR containing the value of the archive Id where the current item, to which this hold is about to be applied, is stored.

301

302

Content Management API IHold :: ItemId

Remarks This property must be set before a hold is placed or released.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or the value is not a syntactically valid Archive Id.

Example [in] IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold); [out] IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { I Hold hold = (IHold)holds.Item(i + 1); string archId = hold.ArchiveId;

IHold :: ItemId This property specifies the identifier of the item to which the hold object refers. The property is read/write.

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

Content Management API IHold :: ItemId

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the current item Id held by this hold.

[in] BSTR newVal

BSTR containing the item Id to set for this hold.

Remarks This property must be set before a hold is placed. The identifier can be a Saveset Id or a Transaction Id. See “Saveset IDs and Transaction IDs” on page 71.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or value passed in is not a syntactically valid Saveset Id or Transaction Id.

Example [in] IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite"; hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60"; holds.Add(hold); [out] IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { IHold hold = (IHold)holds.Item(i + 1); string itemID

= hold.ItemId;

303

304

Content Management API IHold :: Id

IHold :: Id This property identifies the hold object. The property is read/write.

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the current hold Id.

[in] BSTR newVal

BSTR that will contain the new value of the hold Id.

Remarks The maximum length for this property is 128 characters. This property is returned after a hold has been placed, and must be set before a hold can be released.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or newVal is not a syntactically valid Hold Id.

Example [in] IHolds holds = cmAPI.Holds; holds.ConsumerGUID = "{1D938946-329D-4bfa-87FF-9D30B808ADD1}"; IHold hold = cmAPI.Hold; hold.ArchiveId = "1C9EFA88998592944ADB634ACC0D7410D1110000EVSite";

Content Management API IHold :: Status

hold.Id = 123; holds.Add(hold); //add more holds holds.ReleaseHolds; [out] IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { IHold hold = (IHold)holds.Item(i + 1); string ID

= hold.Id;

IHold :: Status This property returns the status of the hold after an attempt to either place or release a hold. The property is read only.

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

Parameters [out, retval] VARIANT* pVal

Pointer to a VARIANT that will contain the current status value.

Remarks The VARTYPE of the variant must be vt = VT_I4.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

305

306

Content Management API IHold :: Metadata

IHold :: Metadata This property returns the metadata that is stored with the hold. The property is read only.

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the metadata for this hold.

Remarks This property is only populated when the IItem.Get method is called and the DetailLevel parameter includes the HoldData bit. See “IItem :: Get” on page 194.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { IHold hold = (IHold)holds.Item(i + 1); string metadata = hold.MetaData;

IHold :: ConsumerGUID This property returns the unique identifier of the calling application that placed the hold. The property is read only.

Content Management API IHold :: GroupId

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

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the consumer GUID of the application that placed the hold.

Remarks The format of the consumer GUID should be as in the following example: {3BC4797A-3238-478b-9CA6-5CC9989078DE}

Any other format will generate an error.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL, or pVal is not a valid GUID.

Example IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { IHold hold = (IHold)holds.Item(i + 1); string conGUID = hold.ConsumerGUID;

IHold :: GroupId This property returns the identifier of the group of holds to which the hold belongs. The property is read only.

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

307

308

Content Management API ICollectionBase : IDispatch

Parameters [out, retval] BSTR* pVal

Pointer to a BSTR that will contain the current group Id.

Remarks See “IHolds :: GroupId” on page 290.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The pVal pointer is NULL.

Example IHolds holds = Item.Holds; for (int i = 0; i < holds.Count ; i++) { IHold hold = (IHold)holds.Item(i + 1); string groupID = hold.GroupId;

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

Syntax interface ICollectionBase : IDispatch

Member summary Table 4-44

ICollectionBase properties

Property

Read/Write

Description

Count

Read only

Number of items in 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.

Item

Read only

Instance of the item at the zero-based index into the collection.

Maximum

Read/Write

Maximum number of items in the collection.

More

Read only

Whether or not there were more items than Maximum.

Table 4-45

ICollectionBase methods

Method

Description

Get

Populate the collection.

Clear

Clear the current collection.

Reset

Reset the object back to the initial state.

Version information This interface is available in Enterprise Vault 2007 or later.

ICollectionBase :: Count This property returns the current number of items in the collection. The property is read only.

Syntax HRESULT Count([out,retval] long* value);

Parameters [out,retval] long* value Number of items in the collection.

309

310

Content Management API ICollectionBase :: _NewEnum

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

value is NULL.

Example [C#] archives.Get(); for (long i = 0; i < archives.Count; i++) { ProcessArchive(archives.Item(i));

ICollectionBase :: _NewEnum This property returns an IEnumVARIANT interface on an object that can be used to enumerate the collection object. This property is hidden in Visual Basic Scripting Edition (VBScript). The property is read only.

Syntax HRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters [out,retval] IUnknown** enumerator

Returned reference to the IUnknown interface of the object.

Remarks This property is a standard property used to support enumerating collections, it is automatically used internally when you use the For Each construct in C#, or VBScript.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

enumerator is NULL.

Content Management API ICollectionBase :: Item

Example [C#] archives.Get(); foreach (IArchive archive in archives) { SearchArchive(archive.Id);

ICollectionBase :: Item This property returns an instance of the item at the zero-based index into the collection treated as a virtual array. The property is read only.

Syntax HRESULT Item([in] long index, [out,retval] IUnknown** item);

Parameters [in] long index

Zero-based index.

[out,retval] IUnknown** item

Reference to an instance of the collection.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

item is NULL, or index is invalid.

Example [C#] archives.Get(); for (long i = 0; i < archives.Count; i++) { IArchive archive = (IArchive)archives.Item(i); SearchArchive(archive.Id);

311

312

Content Management API ICollectionBase :: Maximum

ICollectionBase :: Maximum This property sets the maximum number of items for the collection. The property is read/write.

Syntax HRESULT Maximum([out,retval] long* value); HRESULT Maximum([in] long value);

Parameters [out,retval] long* value

Maximum number of items in the collection.

[in] long value

Required maximum number of items for the collection.

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

Vault stores 5000

■

Archives 5000

■

Items 10000

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

Value is NULL, or value is invalid.

Content Management API ICollectionBase :: More

Example [C#] archives.Maximum = 6000; archives.Get();

ICollectionBase :: More This property indicates whether there were more items available in the collection than specified by Maximum. The property is read only.

Syntax HRESULT More([out,retval] VARIANT_BOOL* value);

Parameters [out,retval] VARIANT_BOOL* value

Pointer to a VARIANT_BOOL which will contain true, if there are more items in the collection than the Maximum number specified. Otherwise it will contain false.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

value is NULL.

Example [C#] archives.Maximum = 6000; archives.Get(); if (archives.More == true) { //do something,

313

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.

Syntax HRESULT Get(void);

Remarks Any existing collection is cleared prior to attempting to repopulate the collection.

Return value S_OK

Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER

The combination of properties used for the collection selection criteria are invalid. See “VaultStores object” on page 107. See “Archives object” on page 119. See “Items object” on page 164.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE

The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY

Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later, if there are insufficient resources the maximum number of records requested should be reduced.

Example [C#] archives.Computer = ""EV1.acme.com"; archives.Permissions =

Content Management API ICollectionBase :: Clear

EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH; archives.ArchiveTypes = EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_SHARED; archives.Get();

ICollectionBase :: Clear This method clears the current collection.

Syntax HRESULT Clear(void);

Remarks Clears all items from the current collection setting it back to the empty state; Count returns zero.

Return value S_OK

Success.

Example [C#] archives.Get(); for (long i = 0; i < archives.Count; i++) { ProcessArchive(archives.Item(i)); } //now clear archives before doing another get with different filters set archives.Clear();

ICollectionBase :: Reset This method resets the collection back to the initial empty state.

315

316

Content Management API ExtendedErrorInfo object

Syntax HRESULT Reset(void);

Remarks All items are cleared from the current collection, if any, and all selection criteria properties are reset back to their default empty values.

Return value S_OK

Success.

Example [C#] archives.Get(); for (long i = 0; i < archives.Count; i++) { ProcessArchive(archives.Item(i)); } //now reset archives before doing another get with different filters set archives.Reset();

ExtendedErrorInfo object This object implements the following interface: ■

IExtendedErrorInfo

This interface makes available properties that provide additional details about the return value of the most recent call to a child object of the parent Content Management API object instance.

Syntax interface IExtendedErrorInfo : IDispatch

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.

Description

Read only

The description for the Content Management API return value.

InnerError

Read only

The associated internal return value.

InnerErrorDescription Read only

The description for the internal return value.

Source

This property is not currently implemented.

Read only

Remarks The ExtendedErrorInfo object is read-only, and is not updated by any subsequent Content Management API call — a new instance of the ExtendedErrorInfo object must be requested from the Content Management API object. The inner error can be any Windows or Enterprise Vault COM return value. It is provided for additional information only; for example, to add to extended logging details. The list of values is not documented, and it is not guaranteed that the same error scenario will return the same inner error value with future versions of Enterprise Vault.

Version information ■

This interface is available from Enterprise Vault 8.0 SP2.

Examples In the following example, the additional information returned by the IExtendedErrorInfo interface shows that the Enterprise Vault server is in Backup Mode: API Error Code: 0x80040302 (Ref: CONTENTMANAGEMENTAPI_E_BUSY)

317

318

Content Management API ExtendedErrorInfo object

API Error Description: Enterprise Vault is temporarily unable to process the request. The server is busy, or has insufficient resources, or is only able to read data due to ongoing backups. Wait a while and then try again. EV Internal Error Code: 0xC0041B85 (Ref STORAGE_E_VAULTSTORE_INBACKUPMODE) EV Internal Error Description: The Vault Store is currently in Backup Mode.

The following example code shows how the ExtendedErrorInfo object is used. [C++] CComPtr pCMAPI; CComPtr pItem; HRESULT hr = pItem->CopyTo(pDestItem); if (FAILED(hr)) { HRESULT hrGLE (S_OK); CComPtr pIUnkErrInfo; hrGLE = pCMAPI->get_LastError(&pIUnkErrInfo);

if (SUCCEEDED(hrGLE)) { CComQIPtr pExtErrInfo(pIUnkErrInfo); if (pExErrInfo != NULL) { HRESULT hrError = S_OK; HRESULT hrInnerError = S_OK; CComBSTR bsErrorDesc; CComBSTR bsInnerErrorDesc; pExErrInfo->get_Error(&hrError);

Content Management API ExtendedErrorInfo object

pExErrInfo->get_InnerError(&hrInnerError); pExErrInfo->get_Description(&bsErrorDesc); pExErrInfo->get_InnerErrorDescription(&bsInnerErrorDesc); // *** Use error info AddExtendedErrorToLogFile(L"Failed to copy archived item", hrError, bsErrorDesc, hrInnerError, bsInnerErrorDesc); } } }

The following example code shows how the ExtendedErrorInfo object is used. [VBScript] private Sub ReportCMAPIError(byref ecmAPI) dim dim dim dim

oExtErr szErrorDesc, szInnerErrorDesc vbError, vbExtError Msg

Err.Clear set oExtErr = ecmAPI.LastError vbError = oExtErr.Error vbExtError = oExtErr.InnerError szErrorDesc = oExtErr.Description szInnerErrorDesc = oExtErr.InnerErrorDescription Msg = "***************************" & vbCrLf & vbCrLf Msg = Msg & "** CM API EXTENDED ERROR INFO" & vbCrLf & vbCrLf Msg = Msg & " Error Code: 0x" & Hex(vbError) & vbCrLf & vbCrLf Msg = Msg & " Error Description: " & szErrorDesc & vbCrLf & vbCrLf Msg = Msg & " InnerError Code: 0x" & Hex(vbExtError) & vbCrLf & vbCrLf

319

320

Content Management API IExtendedErrorInfo :: Error

Msg = Msg & " InnerError Description: " & szInnerErrorDesc & vbCrLf & vbCrLf Msg = Msg & "***************************" WScript.Echo Msg Err.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. This property is read only.

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

Parameters [out,retval] long* pVal Pointer to a long data type containing the Content Management API return value.

Remarks See “Content Management API return values” on page 619.

Return value S_OK

Success.

E_INVALIDARG

pVal is Null.

IExtendedErrorInfo :: Description This property provides the error description for the Content Management API return value. This property is read only.

Content Management API IExtendedErrorInfo :: InnerError

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

Parameters [out,retval] BSTR* pVal

Pointer to a BSTR containing the error description.

Remarks The error description strings are supplied in English only.

Return value S_OK

Success.

E_INVALIDARG pVal is Null

IExtendedErrorInfo :: InnerError This property provides the internal return value associated with the most recent call to a Content Management API method. This property is read only.

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

Parameters [out,retval] long* pVal

Pointer to a long data type containing the internal return value.

Remarks The inner error can be any Windows or Enterprise Vault COM return value. It is provided for additional information only, for example, to add to extended logging details. The list of values is not documented, and it is not guaranteed that the same error scenario will return the same inner error value with future versions of Enterprise Vault.

321

322

Content Management API IExtendedErrorInfo :: InnerErrorDescription

Return value S_OK

Success.

E_INVALIDARG pVal is Null

IExtendedErrorInfo :: InnerErrorDescription This property provides the error description for the Enterprise Vault internal return value. This property is read only.

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

Parameters [out,retval] BSTR* pVal

Pointer to a BSTR containing the error description.

Remarks The error description strings are supplied in English only.

Return value S_OK

Success.

E_INVALIDARG

pVal is Null

IExtendedErrorInfo :: Source This property provides the GUID of the Content Management API object that was the source of the error information. This property is read only.

Syntax HRESULT Source([out, retval] GUID* pVal);

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

336

NSF Manager API INSFManager :: ViewNote

Example The following example shows how to use CloseNSF to close a database, without deleting it: Type type = Type.GetTypeFromProgID( "KVS.EnterpriseVault.LotusDomino.NSFManager"); INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type); try { nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf"); } finally { nsfMgr.CloseNSF(false); nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); }

INSFManager :: ViewNote This method launches the Notes client and opens the specified note.

Syntax HRESULT ViewNote([in] ULONG ulNoteId);

Parameters [in] ULONG ulNoteId The ID of the note, which must exist in the database.

Return value S_OK (success) or standard COM error codes.

Example The following example how to use ViewNote to open a note:

NSF Manager API INSFManager :: ImportNote

Type type = Type.GetTypeFromProgID( "KVS.EnterpriseVault.LotusDomino.NSFManager"); INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type); try { nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf"); uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns"); nsfMgr.ViewNote(noteId); } finally { nsfMgr.CloseNSF(false); nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); }

INSFManager :: ImportNote This method imports a note from a file, or an IStream or ILockBytes object. The note to be imported is in the proprietary Enterprise Vault format, as returned from the Content Management API or by the ExportNote method.

Syntax HRESULT ImportNote( [in] VARIANT vInputNote, [out, retval] ULONG *pulNoteId);

Parameters [in] VARIANT vInputNote

Variant that contains the data to be imported.

[out, retval] ULONG *pulNoteId Returns the ID of the imported note.

Return value S_OK (success) or standard COM error codes.

337

338

NSF Manager API INSFManager :: ExportNote

Example The following example how to use ImportNote to import a note: Type type = Type.GetTypeFromProgID( "KVS.EnterpriseVault.LotusDomino.NSFManager"); INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type); try { nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf"); uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns"); nsfMgr.ViewNote(noteId); } finally { nsfMgr.CloseNSF(false); nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); }

INSFManager :: ExportNote This method exports a note from the NSF database to a file, or an IStream or ILockBytes object. The note exported is in proprietary Enterprise Vault format, and can be passed to the Content Management API or ImportNote method.

Syntax HRESULT ExportNote( [in] ULONG lNoteId, [in] VARIANT vOutputNote);

Parameters [in]_ULONG_ulNoteId

The ID of the note.

[in] VARIANT vOutputNote A variant that contains the exported data.

NSF Manager API INSFManager :: DeleteNote

Return value S_OK (success) or standard COM error codes.

Example The following example shows how to use ExportNote to export a note: Type type = Type.GetTypeFromProgID( "KVS.EnterpriseVault.LotusDomino.NSFManager"); INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type); try { nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf"); nsfMgr.ExportNote(0x8f6, @"c:\EVNotes\storedNote.dvns"); } finally { nsfMgr.CloseNSF(false); nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); }

INSFManager :: DeleteNote This method deletes the note from the NSF database.

Syntax HRESULT DeleteNote([in] ULONG ulNoteId);

Parameters [in] ULONG ulNoteId The ID of the note.

Return value S_OK (success) or standard COM error codes.

339

340

NSF Manager API INSFManager :: InitializeNotes

Example The following example shows how to use DeleteNote to delete a note: Type type = Type.GetTypeFromProgID( "KVS.EnterpriseVault.LotusDomino.NSFManager"); INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type); try { nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf"); nsfMgr.DeleteNote(0x8a6); } finally { nsfMgr.CloseNSF(false); nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); }

INSFManager :: InitializeNotes This method initializes the Notes runtime on the main application thread, or on a worker thread. The main thread must initialize Notes before any worker threads.

Syntax HRESULT InitializeNotes([in] EV_NOTES_INIT_MODE initMode);

Parameters [in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to initialize on the main application thread or a worker thread.

Return value S_OK (success) or standard COM error codes.

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.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 :: TerminateNotes This method terminates the Notes runtime on the main application thread, or on a worker thread. Terminate the Notes runtime on the worker threads before the main thread.

Syntax HRESULT TerminateNotes([in] EV_NOTES_INIT_MODE initMode);

Parameters [in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to terminate on the main application thread or a worker thread.

Return value S_OK (success) or standard COM error codes.

341

342

NSF Manager API INSFManager :: SwitchToID

Example The following example shows how to use TerminateNotes to terminate the Notes runtime: Type type = Type.GetTypeFromProgID( "KVS.EnterpriseVault.LotusDomino.NSFManager"); INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type); try { nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf"); } finally { nsfMgr.CloseNSF(false); nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); }

INSFManager :: SwitchToID This method switches to the specified ID file, which is required when you create an NSF database from a template, or open an NSF database from a remote server.

Syntax HRESULT SwitchToID( [in] BSTR bsIdFilePath, [in] BSTR bsPassword);

Parameters [in] BSTR bsIdFilePath The full path and file name of the ID file.

[in] BSTR bsPassword

The ID file's password.

Return value S_OK (success) or standard COM error codes.

NSF Manager API INSFManager :: SwitchToID

Example The following example shows how to use SwitchToID to switch to a specified ID: Type type = Type.GetTypeFromProgID( "KVS.EnterpriseVault.LotusDomino.NSFManager"); INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type); try { nsfMgr.InitializeNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); nsfMgr.SwitchToID( @"c:\Program Files\Lotus\Notes\Data\IDs\user.id", @"passw0rd"); nsfMgr.OpenNSF(@"DomSvr1/ACME!!mail\user.nsf"); } finally { nsfMgr.CloseNSF(false); nsfMgr.TerminateNotes( EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION); }

343

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

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. Items may be selected using attributes such as

Filtering APIs About the Filtering APIs

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

Exchange Mailbox task

■

Exchange Journaling task

■

Exchange Public Folder task

Both the Domino Filtering API and the File System Filtering API are presented as a set of .NET interfaces. The Domino Filtering API can be used to develop proprietary filters for Domino Journaling tasks. The File System Filtering API can be used to develop proprietary filters for File System Archiving tasks. You can configure multiple filters for a particular type of archiving; the associated archiving task will process these in order. You enable filtering by configuring registry settings for the associated archiving task. The following points summarize the steps you need to take to configure filtering: ■

Develop your filter class using the API interfaces described in this chapter. In the filter you can use the Content Management DiagnosticsAPI class to add tracing and event logging. See “DiagnosticsAPI object” on page 323.

349

350

Filtering APIs Exchange Filtering API

■

Configure the appropriate filtering registry settings for the archiving tasks that you want to perform filtering. The registry settings enable filtering for the archiving task and define the external filters to process. Details of the registry settings are given in the following sections: See “Exchange filtering registry settings” on page 352. See “Domino filtering registry settings” on page 394. See “File System filtering registry settings” on page 395.

■

Restart the associated archiving tasks.

After you upgrade Enterprise Vault, you must update binding redirections in the associated .NET application configuration files to use the newer version of the Enterprise Vault API runtime. For File System filtering, the .NET application configuration file is EvFSAArchivingTask.exe.config. For Domino filtering, the .NET application configuration file is EVLotusDominoJournalTask.exe.config. See “Updating binding redirections in configuration files” on page 54. Details of the filtering APIs are given in the following sections: ■

See “Exchange Filtering API” on page 350.

■

See “Domino Filtering and File System Filtering APIs” on page 389.

Exchange Filtering API The Exchange Filtering API provides a mechanism for COM components to be loaded by the appropriate Exchange archiving task, and called on a per-message basis during the archiving process.

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, Figure 6-1, illustrates how Enterprise Vault implements Exchange external filters: ■

If the registry settings are configured to enable filtering for the Exchange Mailbox, Journaling or Public Folder tasks, the task calls the task filter controller when processing a message.

■

The task filter controller invokes the first external filter, which implements the IExternalFilter interface.

■

The external filter calls the IArchivingControl4 interface, which is implemented by the task filter controller, to retrieve information about the message.

■

The filter processes the message synchronously, using the methods and properties of the IArchivingControl4 interface to set properties that define how the Exchange archiving task is to process the message.

■

Provided the stopFiltering parameter is not set to TRUE, each filter is applied in turn to the message.

351

352

Filtering APIs Exchange Filtering API

■

After the message has been processed by all of the registered filters, the task filter controller then invokes the FilteringComplete method for each filter. This enables the filter to tidy up and release any resources used while processing the message.

■

The Exchange archiving task then completes archiving the message, as modified by the external filters and also taking account of any archiving actions set by the external filters.

Developing Exchange external filters Note: External filters for Exchange filtering must be developed in unmanaged code. This is because the Enterprise Vault Exchange archiving tasks are written in an unmanaged language and Microsoft has not implemented a managed (.NET) MAPI library. A filter should be implemented as an apartment-threaded, in-process COM server that references the following libraries: ■

Enterprise Vault External Filtering Type Library

■

Enterprise Vault Archiving Control Type Library

To develop a filter for Exchange filtering, you need to obtain and install the appropriate Enterprise Vault archiving license.

Exchange filtering registry settings Filtering for Enterprise Vault Exchange Mailbox, Journaling, and Public Folder tasks is enabled using registry settings under the following registry key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering

You add a new key to specify the type of archiving task that is to perform the filtering. The key can be one of the following: ■

Mailbox

■

Journaling

■

PublicFolder

Filtering APIs Exchange Filtering API

For example, to add filtering for the Exchange Mailbox archiving tasks, you add the Mailbox key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox

You then add a string value to the Mailbox key for each of the required external filters. For the name of each filter entry, use the values, 1, 2, 3 and so on. If there are multiple filters, the filter names should form an unbroken numerical sequence. The filters are applied in numerical order. If one number is missing, no further filters are applied. The following example shows three external filters that have been configured for the Exchange Mailbox archiving tasks. HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox 1 = ACompany.Filter1 2 = ACompany.Filter2 4 = ACompany.Filter3

In this case, filter 1 is applied and then filter 2. However, filter processing stops after filter 2 because the filter name sequence is broken. Note: When configuring filtering for Exchange journaling tasks, if the Compliance Accelerator Journaling Connector filter exists, it must be last in the sequence. For the value of each filter entry give the ProgID (ProjectName.ClassName) of the COM class implementing IExternalFilter for this particular filter, as defined in the external filter class registration (.rgs) file. For example: HKCR { EV10FilterVersion.SampleFilterClass.1 = s 'SampleFilterClass Class' {

353

354

Filtering APIs Exchange Filtering API

CLSID = s '{B5FFF252-D74C-4723-B812-41E15B4C57EF}' } EV10FilterVersion.SampleFilterClass = s 'SampleFilterClass Class' { CLSID = s '{B5FFF252-D74C-4723-B812-41E15B4C57EF}' CurVer = s 'EV10FilterVersion.SampleFilterClass.1' } NoRemove CLSID { ForceRemove {B5FFF252-D74C-4723-B812-41E15B4C57EF} = s 'SampleFilterClass Class' { ProgID = s 'EV10FilterVersion.SampleFilterClass.1' VersionIndependentProgID = s 'EV10FilterVersion.SampleFilterClass' ForceRemove 'Programmable' InprocServer32 = s '%MODULE%' { val ThreadingModel = s 'Apartment' } val AppID = s '%APPID%' 'TypeLib' = s '{24798ABC-A921-462a-9964-536E8C37E0A3}' } } }

In the above example, you would use the following value in the filter registry setting: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox 1 = EV10FilterVersion.SampleFilterClass.1

The following optional DWORD values can also be created to control filtering: ■

Override — This setting has the following effect: ■

Exchange Journaling tasks. If created under the Journaling key, and given the value, 1, this setting forces the Exchange Journaling tasks to retry messages that were marked as MARK_DO_NOT_ARCHIVE by a previous filter.

Filtering APIs Exchange Filtering API

If the value is 0, or the setting does not exist, the Exchange Journaling tasks do not retry messages that are marked as MARK_DO_NOT_ARCHIVE. ■

■

Exchange Mailbox and Public Folder tasks. If created under the Maibox or PublicFolder keys, and given the value, 1, this setting turns off custom filtering. If the value is 0, or the setting does not exist, the archiving tasks implement the configured custom filters.

MoveOnFilterFailure — This can be set for Exchange Journaling tasks or Exchange Mailbox tasks. If this setting has the value 1, and an unhandled error occurs in the external filter, the message involved is moved to the folder, Failed external filter. This folder is created automatically if it does not exist. If the value is 0, or the setting does not exist, the archiving tasks take the following action: ■

Exchange Journaling task. When an unhandled error occurs in the external filter, the task moves the associated messages to the folder, Enterprise Vault Journaling Service\Invalid Journal Report in the journal mailbox.

■

Exchange Mailbox task. When an unhandled error occurs in the external filter, the archiving task does not move the associated messages. The task tries to process the messages during each archiving run

In the following example, the Override and MoveOnFilterFailure settings have been created under the Mailbox registry key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Mailbox 1 = ACompany.Filter1 2 = ACompany.Filter2 Override = 0 MoveOnFilterFailure = 1

If you make changes to the custom filtering registry settings, restart the associated archiving tasks to implement the changes. For further details of the filtering registry settings, see the Configuring custom filtering chapter in the the manual, Setting Up Exchange Server Archiving.

355

356

Filtering APIs Enumerations (Exchange filtering)

You can use Dtrace to trace the Enterprise Vault archiving task that is enabled for external filtering. The following Dtrace filter options are useful for verifying that external filtering is working as expected, and for diagnosing problems: DT>f Manage trace entry filter....(? for help) DT Filter>v Current Filter Settings: Include strings: ExternalFiltering EVFilterController

For a description of the Dtrace utility, see the Enterprise Vault Utilities guide.

Enumerations (Exchange filtering) This section lists the enumerations for the Exchange Filtering API.

EV_ACTION enumeration The following enumeration values are defined for EV_ACTION: enum EV_ACTION { NO_ACTION = 0, ARCHIVE_ITEM = 1, MARK_DO_NOT_ARCHIVE = 2, MOVE_DELETED_ITEMS = 3, HARD_DELETE = 4, REQUEST_SHUTDOWN = 5 };

The default value is ARCHIVE_ITEM. When the task is running in report mode the action is ignored.

EV_ATTACHMENT_ACTION enumeration The following enumeration values are defined for EV_ATTACHMENT_ACTION: enum EV_ATTACHMENT_ACTION { NO_ATTACHMENT_ACTION = 0, DELETE_ATTACHMENT = 1,

Filtering APIs Enumerations (Exchange filtering)

REPLACE_ATTACHMENT = 2 };

If the attachment action is to replace attachments, users will see a file called Deleted Attachments.txt attached to messages that have had attachments deleted by the filter. When they open this file, it contains a list of the names of files that have been deleted. The contents of this file are taken from the file, CF_Replace_Attachment.txt, in the Enterprise Vault program folder (typically, C:\Program Files\Enterprise Vault). If required, you can modify the text of this file. For example, you may want to localize the descriptive text.

EV_RETRY_STATUS enumeration The following enumeration values are defined for EV_RETRY_STATUS: enum EV_RETRY_STATUS { UNKNOWN_IF_RETRY = 0, IS_NOT_RETRY = 1, IS_A_RETRY = 2 };

UNKNOWN_IF_RETRY does not indicate an error; it indicates that the task could not determine if the status was a retry. For example, this may be returned if the archiving task does not support detecting retries. Filters should interpret an UNKNOWN_IF_RETRY status as IS_NOT_RETRY.

EV_REARCHIVE_STATUS enumeration The following enumeration values are defined for EV_REARCHIVE_STATUS: enum EV_REARCHIVE_STATUS { UNKNOWN_IF_REARCHIVE = 0, IS_NOT_REARCHIVE = 1, IS_A_REARCHIVE = 2 };

UNKNOWN_IF_REARCHIVE does not indicate an error; it indicates that the task could not determine if the status was a re-archive. For example, this may be returned if the archiving task does not support detecting re-archives. Filters should interpret an UNKNOWN_IF_REARCHIVE status as IS_NOT_REARCHIVE.

357

358

Filtering APIs IExternalFilter interface

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

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.

ProcessFilter

This method is called per-message during the archiving process. The ProcessFilter method is where you process the message to your requirements.

FilteringComplete This method is called after all filters have been processed for the current item.

Remarks The external filter must implement the COM interface, IExternalFilter, which is called by the task filter controller. All methods must be implemented, even if they return only S_OK. If the filter makes changes to the message, and the changes are to be reflected in the Exchange Server store or the Enterprise Vault archive or both, then call the IArchivingControl2 :: MAPISaveChanges method at the end of the method

Filtering APIs IExternalFilter :: Initialize

(ProcessFilter or FilteringComplete) that made the changes to the message. Making a change to the message in ProcessFilter and delaying the MAPISaveChanges call to FilteringComplete is not regarded as good practice.

IExternalFilter :: Initialize This method is called during Exchange archiving task initialization.

Syntax HRESULT Initialize([in] IDispatch *pArchivingControl);

Parameters [in] IDispatch *pArchivingControl

Reference to the IArchvingControl interface.

Remarks Filters are instantiated at task startup and released at task shutdown. The filter should perform any necessary initialization before message processing begins. The interface does not define a corresponding "Uninitialize" method, so any resources created or opened in this method should be released on the final release of the filter implementing the interface.

IExternalFilter :: ProcessFilter This method is called per-message during the archiving process. The ProcessFilter method is where you process the message to your requirements.

Syntax HRESULT ProcessFilter([out, retval] VARIANT_BOOL

*bStopFiltering);

Parameters [out, retval] VARIANT_BOOL *bStopFiltering

Value of true stops the filter controller from processing any more filters on the current item.

359

360

Filtering APIs IExternalFilter :: FilteringComplete

Remarks To get a reference to the message, use the IArchivingControl :: MAPIMessage property. To find or change the current action to be taken on the message, use the IArchivingControl :: Action property. Similarly to change the retention category or archive for the item, use the currentRetentionCategoryId and currentVaultId properties on the IArchivingControl interface. The external filter must be written to handle concurrent calls. If the filter accesses a shared resource, it must use appropriate concurrency protection.

See also ■

See “IArchivingControl :: MAPIMessage” on page 369.

■

See “IArchivingControl :: Action” on page 368.

■

See “IArchivingControl :: currentVaultId” on page 365.

■

See “IArchivingControl :: currentRetentionCategoryId” on page 365.

IExternalFilter :: FilteringComplete This method is called after all filters have been processed for the current item. It can be used to clean up item-specific resources, such as memory or object handles.

Syntax HRESULT FilteringComplete();

Remarks After processing has been completed, the properties on the IArchivingControl interface are read-only. The properties can still be examined so that the filter can determine the final state of the item.

IArchivingControl interface for Exchange filtering The task filter controller implements the following interfaces: ■

IArchivingControl

■

IArchivingControl2

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.

■

Ability to open an archived item from a URL.

■

Method for persisting changes made to messages by external filters, so that the changes are reflected in the Exchange Server store and the Enterprise Vault archive.

The IArchivingControl3 interface extends theIArchivingControl2 interface and adds properties to retrieve sender and recipient information as XML. The IArchivingControl4 interface extends the IArchivingControl3 interface and adds a new method that accepts a VARIANT data structure when specifying string, integer and date custom index property values. This enables searching on date-based selection criteria.

Syntax interface IArchivingControl : IDispatch interface IArchivingControl2 : IArchivingControl interface IArchivingControl3 : IArchivingControl2 interface IArchivingControl4 : IArchivingControl3

Member summary Table 6-2

IArchivingControl properties

Property

Read/Write

Description

currentVaultId

Read/Write

The Id of the archive associated with the current item.

currentRetentionCategoryId

Read/Write

The Id of the retention category associated with the current item.

361

362

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

deleteOriginalItem

Read/Write

Whether the item is to be deleted from the original location after it has been archived.

createShortcutToItem

Read/Write

Whether a shortcut is created in the original location after the item has been archived.

Action

Read/Write

The action to be taken by the archiving task when the filtering process is complete.

MAPISession

Read only

Gets a MAPI session.

MAPIMessage

Read only

A pointer to the current MAPI message.

IndexedPropertiesSet

Read only

Lists the properties that have been added using AddIndexedProperty.

TransactionID

Read only

Identifies archiving action.

AgentType

Read only

Identifies the type of archiving task using the filter.

AgentAssignedRetentionCategoryId

Read only

Identifies the original retention category assigned.

AgentAssignedVaultId

Read only

Identifies the original destination archive.

AttachmentAction

Read/Write

Defines action to be taken when processing message attachments.

RetryStatus

Read only

Indicates if current archiving action is a retry.

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

Table 6-3

IArchivingControl2 properties

Property

Read/Write

Description

BrowserViewURL

Read only

Provides a URL that can be used to present an HTML view of the original item.

NativeItemURL

Read only

Provides a URL that can be use to fetch the original item.

MessageClass

Read only

Identifies the original value of the MAPI Message Class property.

Table 6-4

IArchivingControl methods

Method

Description

AddIndexedProperty

Adds metadata to the item. The metadata will be indexed. This method is deprecated, and may not be supported in a future release. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties.

AddIndexPropertyToSet

Adds custom index properties to a named custom index property set. The custom index property value is specified as a string. This method is deprecated, and may not be supported in a future release. Use IArchivingControl4::AddIndexedPropertyEx to add custom index properties.

363

364

Filtering APIs IArchivingControl interface for Exchange filtering

Table 6-4

IArchivingControl methods (continued)

Method

Description

AddIndexPropertySet

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

GetFilterProperty

Retrieves value of variable set using PutFilterProperty by another filter.

PutFilterProperty

Sets a variable that can be queried by other filters.

Table 6-5

IArchivingControl2 method

Method

Description

MAPISaveChanges

Enables changes to the current message to be saved.

Table 6-6

IArchivingControl3 properties

Method

Description

SenderRecipientXML

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

EnvelopeSenderRecipientXML

Retrieves an XML document containing the sender and recipient information taken from the envelope message.

MessageDirection

Indicates the direction in whish the message was travelling (in relation to the domain defined as internal).

Table 6-7

IArchivingControl4 method

Method

Description

AddIndexedPropertyEx

Adds custom index properties to a named custom index property set. The custom index property value can be specified as a string, integer or date.

Filtering APIs 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, this property enables the caller to determine if the current item is being rearchived. The property is read only.

Syntax HRESULT ReArchiveStatus([out, retval] EV_REARCHIVE_STATUS* pReArchiveStatus);

Parameters [out, retval] EV_REARCHIVE_STATUS* pReArchiveStatus

Pointer to an EV_REARCHIVE _STATUS type containing the current value.

Remarks If this is a rearchive, the transactionID will typically be the same as the previous archive transaction. This property can be used to avoid the following when processing rearchive transactions: ■

Counting the same transaction multiple times.

■

Storing the same transaction (for example, in a database) multiple times.

See “EV_REARCHIVE_STATUS enumeration” on page 357.

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

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

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 Display Name SMTP Email Address Distribution List Display Name Distribution List SMTP Email Address 2007-09-03T23:36:28

Filtering APIs IArchivingControl3 :: EnvelopeSenderRecipientXML

User1 SMTP Email Address Display Name SMTP Email Address

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 Display Name SMTP Email Address Distribution List Display Name Distribution List SMTP Email Address User1 SMTP Email Address Display Name SMTP Email Address Display Name SMTP Email Address Display Name SMTP Email Address

Filtering APIs IArchivingControl3 :: MessageDirection

Note: EnvelopeSenderRecipientXML for Exchange 2007 envelope items will not contain any (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: Legal 2011-09-27T09:51:55Z 10 100

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

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

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, Figure 6-3, illustrates how Enterprise Vault implements file system filters: ■

If the registry settings are configured to enable filtering for the File System Archiving task, the archiving task calls the task filter controller when processing a file in the file system archiving target.

■

The task filter controller invokes the first external filter, which implements the IExternalFilter interface.

■

The filter uses the methods and properties on the IFileArchivingControl interface to retrieve information about the file. Methods and properties provide the filter with access to the file contents or datastream.

■

The filter then processes the file. Methods and properties on the IFileArchivingControl interface enable you to define how the archiving task is to process the file. If the filter makes any modifications to the file, the task filter controller ensures that the modifications are saved back to the file on the file server using CIFS.

■

If there are several filters, each external filter is applied in turn to the message, provided the stopFiltering parameter is not set to TRUE.

■

After all the filters have been applied, the FilteringComplete method for each filter is called to perform any clean up tasks.

■

The File System Archiving task then processes the file according to the properties set by the external filters.

Filtering APIs Domino Filtering and File System Filtering APIs

About file system filter reports When external filters are configured for File System Archiving, information is added to the File System Archiving task report file. The report files are located in the Reports\FSA subfolder of the Enterprise Vault installation folder. In the detailed information for each file processed, the Filter Modifications column shows the filter actions that have been performed on the file. This information is shown in the form: [ filter_name - action, action, ... ] [ filter_name - action, action, ... ] ... where filter_name is the name of the external filter, and action identifies the type of filter action that the archiving task has performed. action can be one of the following: ■

Applied filtering action The archiving task has performed the action defined by the FSAAction enumeration value.

■

Modified file properties File attributes have been modified.

■

Modified index properties Index properties have been added or removed.

■

Performed file stream operation A file or alternate data stream has been opened to read or write.

■

Applied retention category The retention category has been changed.

Summary information for each external filter is displayed in the report section, External Filter Summary. The information shows the number of files or alternate data streams on which the archiving task has performed each filter action. Failure to load a filter is also reported in this section. If files that have already been archived are processed by a filter, only the filtering action can be applied. Therefore only Applied filtering action is reported for these files.

Developing external filters Note: If you plan to supply data to your external filters using XML, be aware that Microsoft does not support the use of MSXML (Microsoft's COM-based XML parser) in .NET applications. This is described in the knowledge base article, KB 815112. Filters developed using the Domino Filtering and File System Filtering APIs must reference the .NET assembly: ■

Symantec.EnterpriseVault.FilterInterfaces.dll

The API interfaces are loaded within the namespace:

393

394

Filtering APIs Domino Filtering and File System Filtering APIs

■

Symantec.EnterpriseVault.FilterInterfaces

You can develop external filters in the programming language of your choice. For clarity, definitions are given using C#.NET syntax. An example file system filter in managed C# is provided in the SDK. For Domino filters, if you want to use the Lotus C API for Lotus Notes/Domino to access the note, we recommend that you use managed C++. The Lotus C API for Lotus Notes/Domino is shipped with the Lotus Notes client. To develop an external filter for Domino journaling, you need to obtain and install an Enterprise Vault Lotus Domino Journaling license. To develop an external filter for File System Archiving, you need to obtain and install an Enterprise Vault File System Archiving license.

Domino filtering registry settings Filtering for Enterprise Vault Domino Journaling tasks is enabled on the Enterprise Vault server using registry settings under the External Filtering key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \Lotus Journaling

If either External Filtering or Lotus Journaling keys do not exist, then you can create them. You create a new string entry for each filter under the Lotus Journaling key. Filter names must be an unbroken numbered sequence starting at 1. The value of the filter name is a string value that contains the name of the .NET assembly and the fully qualified filter class name for the new external filter: PathToFilterAssembly!FilterClassName

A fully-qualified class name includes the namespace. For example, if the class name is CustomFilter, the namespace is Symantec.EnterpriseVault.Domino, and the filter is implemented in Symantec.EnterpriseVault.DominoCustomFilter.dll assembly, then the value of the registry setting should be as follows: Symantec.EnterpriseVault.DominoCustomFilter.dll! Symantec.EnterpriseVault.Domino.CustomFilter

Filtering APIs Domino Filtering and File System Filtering APIs

Note that the class name is case sensitive. If you have installed the Compliance Accelerator Journaling Connector, KVS.EnterpriseVault.LotusDominoMsgHandler.dll! KVS.EnterpriseVault.LotusDomino.CADominoFilter

then it must be the last in the sequence of filters. When you add other filters, you must rename the Journaling Connector to ensure that it remains last in the sequence. Optionally, you can create a DWORD entry with the name Override, if it does not exist. Set its value to 0 (zero). This entry controls whether the Domino Journaling task reexamines any messages that are marked as MARK_DO_NOT_ARCHIVE each time it processes the Domino journaling location. If the value is 0, or the Override entry does not exist, then the Domino Journaling task does not reexamine the messages. To implement changes to the registry settings, restart the associated Domino Journaling tasks.

File System filtering registry settings Filtering for Enterprise Vault File System Archiving tasks is enabled on the Enterprise Vault server using registry settings under the External Filtering key: HKEY_LOCAL_MACHINE \SOFTWARE \Wow6432Node \KVS \Enterprise Vault \External Filtering \File System

If either External Filtering or File Systemkeys do not exist, then you can create them. You create a new string entry for each filter under the File System key. Filter names must be an unbroken numbered sequence starting at 1. The value of the filter name is a string value that contains the name of the .NET assembly and the fully-qualified filter class name for the new external filter: PathToFilterAssembly!FilterClassName

A fully-qualified class name includes the namespace. For example, if the class name is CustomFilter, the namespace is Symantec.EnterpriseVault.FileSystem, and the filter is implemented in

395

396

Filtering APIs Domino Filtering and File System Filtering APIs

Symantec.EnterpriseVault.FileSystemCustomFilter.dll assembly, then the value of the registry setting should be as follows: Symantec.EnterpriseVault.FileSystemCustomFilter.dll! Symantec.EnterpriseVault.FileSystem.CustomFilter

Note that the class name is case sensitive. If the associated File System Archiving task is currently processing archiving targets, you need to restart the task to implement changes to the registry settings. You can use the XML configuration file, EVFSAArchivingTask.exe.config, to control the behavior of the archiving task in the event of filter errors. The configuration file is located in the Enterprise Vault installation folder. You can add the following settings for file system filtering: ■

MoveOnFilterFailure. This setting controls the action taken by the archiving task if it cannot load a filter. If the setting value is "0", then the archiving task stops. If the setting value is "1", then the archiving task loads the next filter, or continues to archive. If the setting is not present in the configuration file, then the default value is "0"; the archiving task stops if it cannot load the filter.

■

MaxFilterError. During archiving, the archiving task keeps a count of the number of filtering errors reported. The MaxFilterError setting lets you configure the maximum number of errors permitted before the archiving task stops. If the setting is not present in the configuration file, the default value is 100.

You need to edit the file and add a section called to hold the settings. This section must also be declared in the element. The settings are added as key/value pairs. The following example shows the file with the settings added:

Filtering APIs Enumerations (Domino filtering)



The settings in this example file have the following effect: ■

key="MaxFilterError" value = "150" — The archiving task will stop if more than 150 filtering errors are reported.

■

key="MoveOnfilterFailure" value = "1" — If the archiving task cannot load a filter, it will try to load the next filter, or continue to archive.

Enumerations (Domino filtering) This section lists the enumerations for the Domino Filtering API.

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

Domino action enumeration The following enumeration values are defined for DominoAction: public enum DominoAction { NO_ACTION = 0, ARCHIVE_ITEM = 1,

397

398

Filtering APIs Enumerations (File System Filtering)

MARK_DO_NOT_ARCHIVE = 2, HARD_DELETE = 4, REQUEST_SHUTDOWN = 5 }

Table 6-9

DominoAction enumeration values

Value

Action

NO_ACTION

Do not archive, delete or mark the item.

ARCHIVE_ITEM

(Default) Archive the item according to the assigned policy.

MARK_DO_NOT_ARCHIVE

Mark the item as processed but do not archive it. The Domino Journaling task does not reexamine marked messages unless the Override setting is configured. See “Domino filtering registry settings” on page 394.

HARD_DELETE

Hard delete the item without archiving it. Note that this option requires Enterprise Vault 8.0 SP5 or later.

REQUEST_SHUTDOWN

Shut down the archiving task.

Enumerations (File System Filtering) This section lists the enumerations for the File System Filtering API.

File System Archiving action enumeration The following actions are supported by the filter controller. These actions can be set by the external filter. public enum FSAAction { DEFAULT_POLICYACTION ARCHIVE_CREATESHORTCUT ARCHIVE_DONOTCREATESHORTCUT DONOTARCHIVE DELETE REQUEST_SHUTDOWN

= = = = = =

0, 1, 2, 3, 4, 5,

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

ARCHIVE_CREATESHORTCUT

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

ARCHIVE_DONOTCREATESHORTCUT

Archive the file and do not create a shortcut.

DONOTARCHIVE

Do not archive the file. The file is left in its original location.

DELETE

Delete the file without archiving it.

REQUEST_SHUTDOWN

Shut down the archiving task.

ARCHIVE_DELETE

Archive the file and delete the original. No shortcut is created.

IExternalFilter interface The external filter must implement the IExternalFilter interface, which is called by the archiving task filter controller: Namespace: Symantec.EnterpriseVault.FilterInterfaces Assembly: Symantec.EnterpriseVault.FilterInterfaces.dll

Syntax public interface IExternalFilter

399

400

Filtering APIs IExternalFilter :: Initialize

Member summary Table 6-11

Member summary

Method

Description

Initialize

Called during the archiving task initialization. The filter should perform any necessary initialization before item processing begins.

ProcessFilter

Called per-item during the archiving process. The ProcessFilter method is where you process the item to your requirements.

FilteringComplete Called after all filters have been processed for the current item. Shutdown

Called during the archiving task shutdown. The filter should perform any necessary clean-up tasks.

Requirements

IExternalFilter :: Initialize This method is called during archiving task initialization.

Syntax void Initialize();

Remarks Filters are instantiated at task startup and released at task shutdown. The filter should perform any necessary initialization before item processing begins.

IExternalFilter :: ProcessFilter This method is called per-item during the archiving process. The ProcessFilter method is where you process the item to your requirements.

Syntax void ProcessFilter(IArchivingControl archivingControl, ref bool stopFiltering);

Filtering APIs IExternalFilter :: FilteringComplete

Parameters IArchivingControl archivingControl

Reference to the ILotusArchivingControl or IFileArchivingControl interface.

ref bool stopFiltering

True value prevents any further filters from being processed for the current item.

Remarks The archivingControl reference is used by the filter in the callback to obtain information about the current item and take appropriate actions. As the archiving task runs in multiple threads, the external filter must be written to handle concurrent calls. If the filter accesses a shared resource, it must use appropriate concurrency protection.

See also ■

See “IArchivingControl interface” on page 402.

■

See “ILotusArchivingControl interface” on page 406.

■

See “IFileArchivingControl interface” on page 410.

IExternalFilter :: FilteringComplete This method is called after all filters have been processed.

Syntax void FilteringComplete();

Remarks This method can be used to clean up resources used to filter the item.

IExternalFilter :: Shutdown This method is called during archiving task shutdown.

Syntax void Shutdown();

401

402

Filtering APIs IArchivingControl interface

Remarks The filter should perform any necessary clean-up tasks.

IArchivingControl interface This task filter controller implements the following interfaces: ■

IArchivingControl

■

ILotusArchivingControl

■

IFileArchivingControl

Namespace: Symantec.EnterpriseVault.FilterInterfaces Assembly: Symantec.EnterpriseVault.FilterInterfaces.dll The methods properties of the interfaces enable an external filter to retrieve and modify properties on the current item. The ILotusArchivingControl interface is implemented by the Domino archiving task filter controller, and is passed to the filter on a per-message basis during the ProcessFilter call. It extends the IArchivingControl interface to provide access to Domino messages from Domino filters. See “ILotusArchivingControl interface” on page 406. The IFileArchivingControl interface is implemented by the File System archiving task filter controller, and is passed to the filter on a per-item basis during the ProcessFilter call. It extends the IArchivingControl interface to provide access to file system archiving targets from file system archiving filters. See “IFileArchivingControl interface” on page 410.

Syntax public interface ILotusArchivingControl : IArchivingControl public interface IFileArchivingControl : IArchivingControl

Member summary Table 6-12

IArchivingControl properties

Property

Read/Write Description

OriginalVaultID

Read only

Original archive for the current item.

CurrentVaultID

Read/Write

Target archive for the current item.

Filtering APIs IArchivingControl :: OriginalVaultID

Table 6-12 Property

IArchivingControl properties (continued) Read/Write Description

OriginalRetentionCategoryID Read only

Original retention category for the current item.

CurrentRetentionCategoryID Read/Write

Retention category assigned to current item.

IndexData

Read only

Metadata added, or to be added, to the current item.

FilterProperties

Read only

A collection of properties for the current item.

IArchivingControl :: OriginalVaultID Retrieves the original archive ID for the current item. This property is read-only.

Syntax string OriginalVaultID {get;}

Remarks This property holds the archive ID originally assigned by the archiving task before any filters where processed. If a filter changes the target archive for the item, this property will remain unchanged. In file system filtering, the value returned is the archive folder Id for the file.

IArchivingControl :: CurrentVaultID This property retrieves or sets the ID of the archive in which the current item will be stored. In file system filtering, the value returned is the archive folder Id for the file. In Domino filtering, this property is read/write. In file system filtering, this property is read only. Attempts to set a value will throw the exception, NotSupportedException.

Syntax string CurrentVaultID {get; set;}

403

404

Filtering APIs IArchivingControl :: OriginalRetentionCategoryID

Exception NotSupportedException

Setting this property is not supported by File System Filtering.

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 is read-only.

Syntax string OriginalRetentionCategoryID {get;}

Remarks This property holds the Id of the retention category originally assigned by the archiving task, before any filters where processed. If a filter changes the retention category for the item, this property will remain unchanged.

IArchivingControl :: CurrentRetentionCategoryID This property defines the retention category for the current item. This property is read/write.

Syntax string CurrentRetentionCategoryID {get; set;}

Remarks Use this property to set or retrieve the ID of the retention category assigned to the current item. An example value is: 18306BF113C2C444096279660836252821b10000EVArchiveSite1

Filtering APIs IArchivingControl :: IndexData

Exceptions ArgumentNullException

Value specified is null.

ArgumentException

Value specified is empty, or does not exist.

IArchivingControl :: IndexData This property is an instance of the IIndexMetadata interface, and enables access to the custom index metadata for the current item. The property is read only.

Syntax IIndexMetadata IndexData {get;}

Remarks See also ■

See “IIndexMetadata interface” on page 424.

IArchivingControl :: FilterProperties This property is an instance of the IKeyedList interface, and enables communication between multiple filters. For example, a filter property can be set by one filter and queried by another. The property is read only.

Syntax IKeyedList FilterProperties {get;}

Remarks The properties listed are shared across all filters. These properties are not stored in Enterprise Vault or reset by Enterprise Vault. The properties can be maintained across multiple messages, if required.

405

406

Filtering APIs ILotusArchivingControl interface

See also ■

See “IKeyedList interface” on page 431.

ILotusArchivingControl interface ILotusArchivingControl is derived from the IArchivingControl interface, and extends the interface to enable filters to access Domino messages. Namespace: Symantec.EnterpriseVault.FilterInterfaces Assembly: Symantec.EnterpriseVault.FilterInterfaces.dll See “IArchivingControl interface” on page 402.

Member summary Table 6-13

ILotusArchivingControl properties

Property

Read/Write

Description

Action

Read/Write

Defines filtering action for current message.

NoteHandle

Read only

Handle to current message.

DatabaseHandle

Read only

Handle to current journal database.

DatabaseName

Read only

Path to current journal database.

SenderRecipientXML

Read only

XML representation of message distribution list.

StoreIdentifier

Read only

Unique Id of Domino message.

Direction

Read only

Direction of message (internal or external).

ILotusArchivingControl :: Action This property defines the filtering action for the current message. The property is read/write.

Syntax DominoAction Action {get; set;}

Filtering APIs ILotusArchivingControl :: NoteHandle

Remarks The filtering action is defined by the DominoAction enumeration. See “Domino action enumeration” on page 397. The default action is to archive the item (ARCHIVE_ITEM enumeration value).

ILotusArchivingControl :: NoteHandle This property retrieves the Lotus C API for Lotus Notes/Domino handle to the current message. The property is read only.

Syntax IntPtr NoteHandle {get;}

Remarks This handle must not be closed by the filter.

ILotusArchivingControl :: DatabaseHandle This property retrieves the Lotus C API for Lotus Notes/Domino handle to the current database. The property is read only.

Syntax IntPtr DatabaseHandle {get;}

Remarks This handle must not be closed by the filter.

ILotusArchivingControl :: DatabaseName This property retrieves the current Domino journal database path. The property is read only.

407

408

Filtering APIs ILotusArchivingControl :: SenderRecipientXML

Syntax string DatabaseName {get;}

Remarks This path is relative to the Data folder.

ILotusArchivingControl :: SenderRecipientXML This property retrieves an XML document containing the sender and recipient information for the current message. The property is read only.

Syntax XmlDocument SenderRecipientXML {get;}

Remarks Any distribution lists are expanded, regardless of the setting of the Expand distribution lists setting on the Advanced page of the Domino Journaling policy in the Enterprise Vault Administration Console. The property value is an XML document representing the sender and recipient information for the current message, including expanded distribution lists. This document is described by the following DTD:

Filtering APIs ILotusArchivingControl :: StoreIdentifier

Example The following is an example of the SenderRecipientXML document: Display Name SMTP_address LotusNotes_address Display Name of DL lotusnotes_address_of_dl Display Name of DL Member lotusnotes_address_of_dl_member Display Name LotusNotes_address

ILotusArchivingControl :: StoreIdentifier This property uniquely identifies the message.

409

410

Filtering APIs ILotusArchivingControl :: Direction

The property is read only.

Syntax string StoreIdentifier {get;}

Remarks The property is derived from the Universal Note ID (UNID) and Originator ID (OID) that are assigned by the Domino server. The UNID and OID are defined as follows: UNID (Universal Note ID)

Identifies all the copies of a note, regardless of location or time. Every copy of a note has the same UNID, and the UNID does not change when a note is modified.

OID (Originator ID)

Identifies a particular revision of a note, regardless of location. Every copy of a note has the same OID, but the OID changes when the note is modified.

ILotusArchivingControl :: Direction This property indicates the direction in which the message was travelling (in relation to the domain defined as internal).

Syntax MSG_DIRECTION Direction {get;}

Remarks The property value is an enumerated value. See “Message direction enumeration” on page 397.

IFileArchivingControl interface The IFileArchivingControl interface is derived from IArchivingControl, and refines the interface for file system archiving targets. Namespace: Symantec.EnterpriseVault.FilterInterfaces Assembly: Symantec.EnterpriseVault.FilterInterfaces.dll See “IArchivingControl interface” on page 402.

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.

Name

Read/Write

Retrieves or modifies the file name only.

Attributes

Read/Write

Retrieves or modifies the file attributes.

LastWriteTimeUtc Read/Write

Retrieves or modifies the last modified date (UTC) of the file.

LastAccessTimeUtc Read/Write

Retrieves or modifies the last accessed date (UTC) of the file.

CreationTimeUtc

Read/Write

Retrieves or modifies the creation date (UTC) of the file.

Length

Read only

Retrieves the size of the file.

ExtendedAttributes Read only

Retrieves the extended attributes of the file.

StreamNames

Lists all alternate data streams.

Table 6-15 Method

Read only

IFileArchivingControl methods Description

GetAccessControl Retrieves the access control of the file. SetAccessControl

Modifies the access control of the file.

Open

Reads, writes and searches for the file contents (default stream).

OpenStream

Reads, writes and searches for the alternate data streams.

DeleteStream

Deletes an alternate data stream.

IFileArchivingControl :: Action This property defines the filtering action for the current item. The property is read/write.

411

412

Filtering APIs IFileArchivingControl :: Name

Syntax FSAAction Action {get; set;}

Value Action

FSAAction enumeration value.

Remarks The filtering action is defined by the FSAAction enumeration. See “File System Archiving action enumeration” on page 398. By default the action taken is the one defined in the policy for the folder or volume in which the file is located.

Exception ArgumentOutOfRangeException

Value specified is an invalid value for FSAAction.

IFileArchivingControl :: Name This property holds the file name of the current item, and can be used to rename the file. The property is read/write.

Syntax string Name {get; set;}

Value string FileName

File name of the current item.

Remarks The value does not include the path to the file.

Filtering APIs IFileArchivingControl :: Attributes

Exceptions ArgumentNullException

Value specified is null.

ArgumentException

A file with the specified name already exists, or the filename specified includes invalid characters. Filenames cannot include any of the following characters: /\:?”|

PathTooLongException

The specified path, filename, or both exceed the system-defined maximum length. Filename cannot be more than 255 characters.

UnathorizedAccessException

The caller does not have the required permission, or the path specified is read-only.

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example string fileName = archivingControl.Name; // rename file as fileName.txt archivingControl.Name = fileName + ".txt";

IFileArchivingControl :: Attributes This property provides the file attributes of the current item. The property is read/write.

Syntax System.IO.FileAttributes Attributes {get; set;}

Value System.IO.FileAttributes Attributes

System.IO.FileAttributes enumeration value.

413

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, or the path specified is read-only.

NoteSupportedException

One or more unsupported file attribute has been specified: Device, Directory, Offline, Temporary.

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example

IFileArchivingControl :: CreationTimeUtc This property provides the date and time (UTC) when the current item was created. The property is read/write.

Syntax System.DateTime CreationTimeUtc {get; set;}

Value System.DateTime CreationTimeUtc

UTC datetime.

Filtering APIs IFileArchivingControl :: LastAccessTimeUtc

Exceptions ArgumentOutOfRangeException

The value specified is outside the range of dates, or times, or both, that are permitted for this operation.

UnathorizedAccessException

The caller does not have the required permission, or the path specified is read-only, and the access is other than read.

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example

IFileArchivingControl :: LastAccessTimeUtc This property provides the date and time (UTC) when the current item was last accessed. The property is read/write.

Syntax System.DateTime LastAccessTimeUtc {get; set;}

Value System.DateTime LastAccessTimeUtc UTC datetime

Exceptions ArgumentOutOfRangeException

The value specified is outside the range of dates, or times, or both, that are permitted for this operation.

UnathorizedAccessException

The caller does not have the required permission, or the path specified is read-only, and the access is other than read.

415

416

Filtering APIs IFileArchivingControl :: LastWriteTimeUtc

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example

IFileArchivingControl :: LastWriteTimeUtc This property provides the date and time (UTC) when the current item was last modified. The property is read/write.

Syntax System.DateTime LastWriteTimeUtc {get; set;}

Value System.DateTime LastWriteTimeUtc

UTC datetime

Exceptions ArgumentOutOfRangeException

The value specified is outside the range of dates, or times, or both, that are permitted for this operation.

UnathorizedAccessException

The caller does not have the required permission, or the path specified is read-only.

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Filtering APIs IFileArchivingControl :: GetAccessControl

Example

IFileArchivingControl :: GetAccessControl This method returns the access control that is set on the current file. The method uses the .NET Framework AccessControlSections enumeration in the System.Security.AccessControl namespace.

Syntax System.Security.AccessControl.FileSecurity GetAccessControl( AccessControlSections includeSections);

Parameter AccessControlSections includeSections

AccessControlSections enumeration value.

Exception NotImplementedException

Example

IFileArchivingControl :: SetAccessControl This method sets the access control on the current file. The method uses the .NET Framework AccessControlSections enumeration in the System.Security.AccessControl namespace.

Syntax void SetAccessControl( System.Security.AccessControl.FileSecurity fileSecurity);

Parameter System.Security.AccessControl. FileSecurity fileSecurity

AccessControlSections enumeration value.

417

418

Filtering APIs IFileArchivingControl :: Length

Exceptions NotImplementedException

Example

IFileArchivingControl :: Length This property provides the size of the current file. The property is read only.

Syntax System.UInt64 Length {get;}

Value System.UInt64 Length

Size of file in bytes.

Example

IFileArchivingControl :: Open This method is used to open the default stream for reading or writing. The method uses the following .NET Framework enumerations in the System.IO namespace: FileMode enumeration

Defines constants for read, write, or read/write access to a file.

FileAccess enumeration

Specifies how the operating system should open a file.

FileShare enumeration

Contains constants for controlling the kind of access other FileStream objects can have to the same file.

Syntax System.IO.Stream Open(FileMode mode, FileAccess access, FileShare share);

Filtering APIs IFileArchivingControl :: Open

Parameters FileMode mode

FileMode enumeration value.

FileAccess access

FileAccess enumeration value.

FileShare share

FileShare enumeration value.

Remarks The following FileMode values are not supported: ■

FileMode.Create

■

FileMode.CreateNew

■

FileMode.OpenOrCreate

■

FileMode.Append

The FileShare value, FileShare.Inheritable, is not supported.

Exceptions ArgumentOutOfRangeException

The value specified for FileMode, FileAccess, or FileShare is invalid.

ArgumentException

■

UnathorizedAccessException

The caller does not have the required permission, or the path specified is read-only, and the access is other than read.

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

FileMode specified is one of Create, CreateNew, OpenOrCreate, or Append. ■ The FileAccess specified is ‘read’, and the FileMode specified is Truncate or Append.

419

420

Filtering APIs IFileArchivingControl :: StreamNames

Example

IFileArchivingControl :: StreamNames This property lists the names of alternate data streams. The property is read only.

Syntax String[] StreamNames {get;}

Value String[] StreamNames

Names of alternate data stream.

Exception FilterControllerException

For any errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example string [] alternateDataStreams = archivingControl.StreamNames; foreach (var v in alternateDataStreams) { // add code }

IFileArchivingControl :: OpenStream This method is used to open an alternate data stream for reading or writing. The method uses the following .NET Framework enumerations in the System.IO namespace: FileMode enumeration

Defines constants for read, write, or read/write access to the stream.

Filtering APIs IFileArchivingControl :: OpenStream

FileAccess enumeration

Specifies how the operating system should open the stream.

FileShare enumeration

Contains constants for controlling the kind of access other filestream objects can have to the same stream.

Syntax System.IO.Stream OpenStream(FileMode mode, FileAccess access, FileShare share, String streamName);

Parameters FileMode mode

System.IO.FileMode enumeration value

FileAccess access

System.IO.FileAccess enumeration value

FileShare share

System.IO.FileShare enumeration value

string streamName

Name of alternate data stream

Remarks The FileShare value, FileShare.Inheritable, is not supported.

Exceptions ArgumentNullException

The stream name specified is null.

ArgumentOutOfRangeException

The value specified for FileMode, FileAccess or FileShare is invalid.

ArgumentException

The FileAccess value specified is ‘read’, and the FileMode specified is Truncate or Append.

UnathorizedAccessException

The caller does not have the required permission, or the path specified is read-only, and the access is other than read.

421

422

Filtering APIs IFileArchivingControl :: DeleteStream

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example string [] alternateDataStreams = archivingControl.StreamNames; foreach (var v in alternateDataStreams) { using(Stream ads = archivingControl.Open(FileMode.Open, FileAccess.Read, FileShare.Read, v)) { long bytesInAds = ads.Length; } }

IFileArchivingControl :: DeleteStream This method is used to delete an alternate data stream.

Syntax bool DeleteStream(string streamName);

Parameters string streamName

Name of alternate data stream

Exceptions ArgumentNullException

The stream name specified is null.

ArgumentException

The stream name is empty, or has invalid characters.

UnathorizedAccessException

The caller does not have the required permission, or the path specified is read-only.

Filtering APIs IFileArchivingControl :: ExtendedAttributes

FilterControllerException

For any other errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example bool deleted = archivingControl.DeleteStream("adsName");

IFileArchivingControl :: ExtendedAttributes This property returns a name/value pair for the extended attributes that exist on the file.

Syntax System.Collections.Generic.Dictionary ExtendedAttributes {get;}

Parameters ExtendedAttributes

Name/value list.

Exception FilterControllerException

For any errors during the operation (for example, an IO error). Inner exception will provide information about the actual error.

Example Dictionary extendedAttribs = archivingControl.ExtendedAttributes; foreach (var v in extendedAttribs) Console.WriteLine("EA Name:" + v.Key + "EA Value:" + v.Value);

423

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, and retrieve additional properties that have been previously added to the index using Add (). Namespace: Symantec.EnterpriseVault.FilterInterfaces Assembly: Symantec.EnterpriseVault.FilterInterfaces.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.

Table 6-17

IIndexMetadata methods

Method

Description

Count

Returns the current count of properties.

Add

Add a custom index metadata property to the current item.

Clear

Remove all custom index metadata properties from the current item.

ToXML

Persists the custom index metadata to XML.

FromXML

Loads the custom index metadata from XML.

Remarks The IIndexMetadata interface inherits from the IEnumerable interface and hence supports standard enumeration support for the collection of properties. When enumerating, each property is returned as an instance of the IIndexProperty interface. See “IIndexProperty interface” on page 428. See “Adding custom index metadata” on page 72.

Filtering APIs IIndexMetadata :: ToXML

IIndexMetadata :: ToXML This method returns the custom index metadata as an XML document.

Syntax string ToXML(bool formattedLayout);

Parameters bool formattedLayout

If true, the XML returned will be formatted in lines and indented appropriately.

Remarks The XML can be loaded into an ISimpleIndexMetadata object, as defined in the Content Management API. See “SimpleIndexMetadata object” on page 256.

IIndexMetadata :: FromXML This method loads the custom index metadata from an XML document.

Syntax void FromXML(string xmlIndexMetadata);

Parameters [in] BSTR xmlIndexMetadata

The XML stream to input.

Remarks Use the Add method to add item specific values. The XML schema is not published, as the Add method should always be used to add metadata properties. Do not change the structure of the XML.

425

426

Filtering APIs IIndexMetadata :: Add

IIndexMetadata :: Add This method adds a property to the custom index metadata for the current item. The custom index metadata will be added to the archive's item once the item has been archived.

Syntax void Add(string propertySet, string propertyName, string propertyValue, bool propertySearchable, bool propertyRetrievable); void Add(string propertySet, string propertyName, DateTime propertyValue, bool propertySearchable, bool propertyRetrievable); void Add(string propertySet, string propertyName, long propertyValue, bool propertySearchable, bool propertyRetrievable); void Add(string propertySet, string propertyName, ulong propertyValue, bool propertySearchable, bool propertyRetrievable);

Parameters string propertySet

Name of the property set.

string propertyName

Name of the property.

string propertyValue DateTime propertyValue long propertyValue ulong propertyValue

Property value.

bool propertySearchable

Whether property can be searched for using Search API.

bool propertyRetrievable

Whether property can be retrieved and displayed in search results.

Filtering APIs IIndexMetadata :: Add

Remarks The Add method can be called repeatedly to add multiple properties to the index. The overloads of the Add method allow the addition of strings, integers or dateTime values. Table 6-18 lists the supported variant types for propertyValue. Table 6-18

Supported types for propertyValue

Value type

Variant type

Note

String

VT_BSTR

Datetime

VT_DATE

Limited to the UTC date range of 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

Properties can be multi-valued. When adding a property, the existence of that property within the specified property set is checked and, if present, the value is added as an element of that property. If the Searchable property is true, the property will be indexed. If the Retrievable property is true, the property is stored with the item in the archive. The property information can then be retrieved and displayed later with the item in search results. The default value is false. It is good practice to use a named property set in order to avoid name clashes with other external filter additions. Suitable names would be your company name or the filter application name. The following property set names are reserved: ■

Vault

■

EnterpriseVault

■

KVS

■

Veritas

■

Symantec

Property sets do not need to be created before properties are added to them. When you use Add() to add a property to the index, the property will be added to the property set specified by propertySet, if the property set exists. If the set does not exist, it will be created first.

427

428

Filtering APIs IIndexMetadata :: Clear

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.

IIndexMetadata :: Clear This method clears all properties from the IIndexMetadata object for the current item.

Syntax void Clear();

IIndexMetadata :: Count This method retrieves the number of properties in the IndexMetadata object for the current item.

Syntax int Count();

IIndexMetadata :: DateTimesUTC This property sets or retrieves whether the date and time properties are input and output in UTC or local system time.

Syntax bool DateTimeUTC {get; set;}

Remarks This property sets or retrieves whether the date and time properties are input and output in UTC or local system time.

IIndexProperty interface The IIndexProperty interface details a a custom index metadata property within an IIndexMetadata collection.

Filtering APIs IIndexProperty interface

Namespace: Symantec.EnterpriseVault.FilterInterfaces Assembly: Symantec.EnterpriseVault.FilterInterfaces.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.

Name

Read only

The name of the property.

Value

Read only

The value assigned to the property.

Searchable

Read only

Defines whether the property is to be added to the item index.

Retrievable

Read only

Defines whether the property is to be stored in the saveset.

Remarks An instance of this interface is returned when enumerating an IIndexMetadata collection.

Example [C#]

IIndexMetadata custProps = archivingControl.IndexMetadata; foreach(IIndexProperty prop in custProps) { if (prop.Searchable) { searchableProps.Add(prop.Set, prop.Name, prop.Value); } }

429

430

Filtering APIs IIndexProperty :: Set

IIndexProperty :: Set This property holds the name of the property set. The property is read only.

Syntax string Set {get;}

IIndexProperty :: Name This property holds the name of the custom index property. The property is read only.

Syntax string Name

{get;}

IIndexProperty :: Value This property holds the value of the index property. The property is read only.

Syntax System.Object Value {get;}

Remarks The object will be a string, integer, or date/time value.

Example [C#]

IIndexMetadata custProps = archivingControl.IndexMetadata; foreach(IIndexProperty prop in custProps) { if (prop.Searchable && (prop.Value.GetType() ==

Filtering APIs IIndexProperty :: Searchable

typeof(DateTime))) { searchableDateProps.Add(prop.Set, prop.Name, (DateTime)prop.Value); } }

IIndexProperty :: Searchable This property indicates whether the property can be returned in search results when using the Search API. The property is read only.

Syntax bool Searchable {get;}

IIndexProperty :: Retrievable This property indicates whether the index property can be retrieved and displayed with search results when using the Search API. The property is read only.

Syntax bool Retrievable {get;}

IKeyedList interface This interface enables multiple filters to access a list of filter properties. The collection allows both random access by index and keyed access using a key value. Namespace: Symantec.EnterpriseVault.FilterInterfaces Assembly: Symantec.EnterpriseVault.FilterInterfaces.dll

Syntax public interface IKeyedList : ICollection, IDictionary,

IEnumerable

431

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.

RemoveAt

Removes a filter property from the specified position in the list.

See also ■

See “IArchivingControl :: FilterProperties” on page 405.

IKeyedList :: Insert Inserts a filter property into the list at the specified position.

Syntax void Insert(System.Int32 index, System.Object key, System.Object value);

Parameters System.Int32 index

The position to insert into the list.

System.Object key

The key for the filter property.

System.Object value

The value of the filter property.

Remarks The elements that follow the insertion point are moved down to accommodate the new element. If index equals the number of items in the list, then the value is appended at the end of the list. An exception is reported if the specified index is out of range.

Filtering APIs IKeyedList :: RemoveAt

IKeyedList :: RemoveAt Removes a filter property from the list at the specified position.

Syntax void RemoveAt(Int32 index);

Parameter Int32 index The position in the list.

Remarks The elements that follow the removed element move up to occupy the vacated spot. An exception is reported if the index is out of range.

433

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

438

Search API About Search API

■

ISearchResults2 :: LoadResults

■

SearchResult object

■

ISearchResult :: Result

■

ISearchResult :: Number

■

ISearchResult :: Prop

■

ISearchResult :: Prop2

■

ISearchResult2 :: Count

■

ISearchResult2 :: Item

■

ISearchResult2 :: DateTimesUTC

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

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

Search API Introduction to Enterprise Vault indexing

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

Index Servers and Index Server groups The role of the Index Server can be summarized as follows: ■

On instruction from the Storage service, the Index Server indexes items. This can be as the items are archived, or later, depending on how the administrator has configured indexing.

■

In response to search requests from the Enterprise Vault Web Server, or third-party search applications using the Search API, the Index Server searches the indexes and returns information about the archived items that match the search criteria.

■

The Index Server ensures that indexes are complete, and automatically updates the index every hour.

Index Servers can be standalone, or in Index Server groups. Figure 7-1 shows a standalone Index Server configuration. An Index Server can only be standalone if the Storage service and Index Server are collocated on an Enterprise Vault server. Figure 7-1

Standalone Index Server

Enterprise Vault server 1 Storage service

Index Server

Server 1 index locations

Vault stores

Index Server groups provide load-balanced indexing services for large or distributed Enterprise Vault environments. In a distributed environment, some Enterprise Vault servers may host Storage services, while others host Index Servers. Figure 7-2 shows an example of this environment.

439

440

Search API 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, the administrator performs the following tasks: ■

Creates Index Server groups, and add to each group Index Servers on different Enterprise Vault servers.

■

Assigns physical index locations to each Index Server.

■

Assigns each vault store to either a standalone Index Server, or an Index Server group. The Index Servers in a group share the task of indexing the items stored in the archives in the vault stores assigned to the group.

Search API Introduction to Enterprise Vault indexing

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

441

442

Search API 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. If required, different levels can be set for different groups of users. There are two levels of indexing: brief and full: ■

Brief indexing. This enables users to search on attributes of an archived item such as Author, Subject, Recipients, Created Date, File Extension, Retention Category and so on. With brief indexing, the content of the item is not indexed.

■

Full indexing. This enables users to search as for brief indexing, and also provides content searching.

Search API Introduction to Enterprise Vault indexing

Obviously, the more information that is indexed, the more disk space is required for the index. The level of indexing, and when an item is indexed for a particular archive, can be controlled using the Content Management API. See “IArchive :: IndexLevel” on page 142. See “IArchive :: IndexUrgency” on page 140.

About index properties Enterprise Vault indexes a set of system properties for each item. The system properties indexed depend on the level of indexing configured when the item is archived. See “System properties” on page 596. How Enterprise Vault processes sender and recipient details in different types of messages is described in an appendix to this guide. See “About storing and retrieving message items” on page 627. In addition to the system index properties, you can add custom index metadata properties to the index document for an item. These properties may be required to enable users or third-party applications to search for particular items. Custom index metadata can be added using the Content Management API or the Filtering APIs. See “Adding custom index metadata” on page 72. ■

In the Content Management API, use the methods on the ISimpleIndexMetadata interface. See “SimpleIndexMetadata object” on page 256. See “IArchiveMetaData :: IndexData” on page 236.

■

In the Exchange Filtering API, use the method IArchivingControl4 :: AddIndexedPropertyEx. Custom filtering is available for Exchange Mailbox Archiving Tasks, Exchange Public Folder Tasks and Exchange Journaling Tasks. See “IArchivingControl interface for Exchange filtering” on page 360.

■

In the Domino Filtering API and File System Filtering API, use the Add method in the IndexMetadata class. See “IArchivingControl interface” on page 402.

Granularity of search results In Enterprise Vault 10 and later, searches are performed using item granularity. When an item is indexed, there is a single index document for the top-level item

443

444

Search API Introduction to Enterprise Vault indexing

and any attachments; this means that the top-level item and attachments are searched as a single item. When a search is performed, the single index entity (containing both top-level items and attachments) is searched, and only top-level items are returned in the results. Even if the search criteria is matched in one or more attachments, only the associated top-level item is returned in the results. Attachments can be accessed from the top-level items. In releases before Enterprise Vault 10 the default indexing schema implemented was attachment granularity. With attachment granularity, an index document was created for the top-level item (such as a message), and separate index documents were created for each attachment; each nested message and attachment was stored in a separate index document. Searches returned both top-level items and individual attachments. In Enterprise Vault 9 and earlier releases, you could configure Enterprise Vault to use the item granularity schema by configuring the registry setting, SchemaType, in the following location: HKEY_LOCAL_MACHINE \SOFTWARE \KVS \Enterprise Vault \Indexing

However, this only tended to be configured on large systems that performed very complex searching, such as those performed by Symantec Compliance and Discovery Accelerator products. Searches on index volumes that use different schemas may behave differently. The differences can be summarized as follows: ■

Attachment granularity searches (32-bit indexes only). Results may contain both top-level items and attachments. A search for "John Doe" AND "Widgets Corp" will return any items or attachments that contain both "John Doe" and "Widgets Corp" in the same index document.

■

Item granularity searches (64-bit indexes, and 32-bit indexes where SchemaType registry setting was configured). Only the top level item is returned when an attachment matches the criteria. No indication is given as to which attachment matches the criteria. Searches for terms that are combined using AND may return more results than were returned with the attachment granularity schema. This is because index data for an item and any attachments are stored in the same index document. A search for for "John Doe" AND "Widgets Corp" may return an

Search API Using the Search API

item which has "John Doe" in attachment 1, and "Widgets Corp" in attachment 3. Searching across indexes that have been created using different granularity schemas is supported on Enterprise Vault 10 and later.

Using the Search API For programming notes on using Enterprise Vault APIs with .NET managed code, and information about code samples in this manual, see the "Programming notes" section. See “Programming notes” on page 56. All the components required for using the Search API are contained in IndexClient.dll. ■

SearchQuery object is used to construct search queries.

■

IndexVolumeSets object enables access to a collection of IndexVolumeSet objects.

■

IndexVolumeSet object provides properties that expose information about the index volume set.

■

IndexSearch2 object is used to select an index to search, and submit a search query to return some search results.

■

SearchResults object is used to enumerate through a set of search results.

■

SearchResult object is used to enumerate through the index property values returned for each search hit (search result).

Briefly, the process of using the Search API is as follows ■

Get an instance of the Search Query object. You can do this in the usual manner using CoCreateInstance directly (C++), or indirectly using the new operator (.NET managed code).

■

Build the query. You do this by adding various terms and operations to the query object using the ISearchQuery2 interface properties and methods. See “Constructing a search query” on page 446.

■

Get an instance of the IndexSearch2 object and submit the search by calling the Search method of IndexSearch2 interface. See “Performing a search” on page 449.

■

This returns a SearchResults object, which in turn is used get SearchResult object instances for each of the search hits returned in the SearchResults

445

446

Search API Using the Search API

object. (You do not have to obtain or create the SearchResults or SearchResult objects). See “Processing the search results” on page 452.

Constructing a search query Take for example the following query expressed in words: The email Author is John Doe or Alan Smith, and its Subject contains the phrase "Financial Reports", and its Document Date is earlier than 17 May 2001. This query can be broken down into its constituent parts. There are three properties (in a SQL query, these would be the fields or columns in a table): ■

Author

■

Subject

■

Document Date

In order to find the correct emails, we need to attach search conditions to each of these properties: ■

Author - is either John Doe or Alan Smith

■

Subject - this must contain the phrase "Financial Reports"

■

Document Date - this must be earlier than 17th May 2001

The words in italics are the operators within the query. The Search API does not have a "less than" or "greater than" operator so it will be necessary to use a Range for the Document Date: ■

Document Date - this must be between 1st January 1970 and 16th May 2001

The query can now be rewritten as follows: Find All emails where Author = ("Fred Bloggs" or "John Smith") and (Subject contains the phrase "Financial Reports") and (Document Date is between "1st January 1970 and 17th May 2001") The property name, for example, Author, would normally be one of the Enterprise Vault system index property names. See “System properties” on page 596. In addition to system property names, custom properties defined by the user can also be used.

Search API Using the Search API

Any number of terms can be added to a SearchQuery object. By default, they are all combined using the AND operator. Different operators can be specified using the Combine, AddOp, or AddQuery methods: ■

Combine takes two SearchQuery objects, each containing one or more terms and an operator. The method creates a new search query containing all the terms in both objects, combined with the specified operator. This new query can be used in a further Combine operation to create searches of arbitrary complexity.

■

AddQuery is similar to Combine, but instead of taking two SearchQuery objects and combining them to create a third, it incorporates the second object into the first.

■

AddOp combines one or more of the terms previously added to the SearchQuery object with the specified operator.

All three methods can be used interchangeably, and at different stages in the construction of a single search query. Which approach you use depends solely on your preference. To start to construct the earlier example query, you use the AddTerm method of the ISearchQuery interface. AddTerm has the parameters: property, value, search query flag. If SetTerm is used, it clears out any previous query. The search query flag determines how to process individual terms added to a search query. See “ESearchQueryFlags enumeration” on page 458. The first term could be added to the query as follows: AddTerm(IndexPropAUTH, "John Doe",

ESQPhrase);

Then the second term could be added to the query as follows: AddTerm(IndexPropAUTH, "Alan Smith", ESQPhrase);

Now the above terms need to be combined using the OR operator. This is done using the AddOp method: AddOp(ESQor, ESQBinary)

The query is built up using a reverse Polish system; the operator is applied to the previous x "objects" to create a new one, where x is determined by the value of the second parameter to AppOp, the search object scope. See “ISearchQuery :: AddOp” on page 478. The operator itself can be obtained from the ESearchQueryOperators enumeration.

447

448

Search API Using the Search API

See “ESearchQueryOperators enumeration” on page 459. In the example query, two more terms can now be added; the Subject term and the date range term: AddTerm(IndexPropSubj, "Financial Results", ESQPhrase) AddRange(IndexPropDate, 1st January 1970, 16th May 2001, ESQany)

(In reality, you would use the appropriate DateTime object for the programming language being used). The three parts of the query need to be combined using the AND operator. (The first part is the result of the first call to AddOp. The second and third parts are the terms being added in this operation): AppOp(ESQand, ESQQternary)

The resulting query now represents the original query that was expressed in words. The constructed query can be used by the Search method of the IndexSearch2 interface to search the index of an archive. The search query operator, ESQfilter, is a special operator for performing complex searches, such as those required by the Enterprise Vault Compliance and Discovery Accelerator products. See “ESQfilter searches” on page 448.

ESQfilter searches ESQfilter is similar to ESQ but more powerful. The following summarizes how this operator works: ■

A search is performed using the first query. This searches top-level items only. (For example, this term could specify a date range to be searched).

■

A separate search is performed using subsequent queries. This searches both top-level items and attachments. (For example, words in message subject or content).

■

The results are compared and any result from the second search which has an associated top-level item that matches a result from the first query search is added to the results.

Only top-level items are returned in results; if a search query is satisfied in an attachment, the associated top-level item is returned in results. Note that the Options setting of the Search method is ignored if the search uses the operator ESQfilter.

Search API Using the Search API

This type of search is particularly efficient for compliance or discovery type searches.

Special characters in search queries In addition to the search query flags, the string value being searched for can contain special characters to modify the search behavior. Individual words are normally separated with spaces. ■

If words are separated by punctuation (the period is preferred, but most punctuation has the same effect), they are treated as a sub-phrase. For example, if "white blue.green" is specified with ESQany, then the search will look for items containing the single word "white" or the phrase "blue green".

■

If a word or sub-phrase is preceded by + (a single plus character), that word must be found. For example, "white blue +green" means find items containing the word "green", plus at least one of "white or blue".

■

If a word or sub-phrase is preceded by - (a single minus character), that word must not be found. For example, "domain1.com -domain2.com". This finds items sent to "domain1.com" that were not also sent to "domain2.com".

■

If the entire string is being treated as a single phrase anyway (for example, ESQphrase), none of the above values has any effect.

■

To search using wildcards, use an asterisk (*) to find zero or more characters, and a question mark (?) to find any single character. For example, "min*" matches the words "minutes", "minimum", and so on. When searching indexes created before Enterprise Vault 10, there must be at least three other characters before a wildcard.

Finally, words like "and" and "or" have no special meaning in query values (and cannot be given any special meaning). They will be searched for like any other word. So, for example, to search for documents containing both "financial" and "hint", search for the string "financial hint" using ESQall.

Performing a search The index is searched using the methods and properties of the IIndexSearch2 interface. Before initiating the search, set requirements for the search and search results using methods and properties of the IIndexSearch2 interface: ■

SelectArchive method. Use this to specify the index to search. The index is identified using the Id of the associated archive.

449

450

Search API 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 Id of an archive can also be discovered using the Enterprise Vault Administration Console: ■

In the Enterprise Vault Administration Console, double-click the archive to display the properties dialog and click the Advanced tab. The archive Id is displayed on the advanced properties page.

■

SelectIndexVolumeSet method. If you do not want Enterprise Vault to perform a federated search across multiple index volumes, use this method to set the Id of the archive's index volume set to search. See “Searching indexes with multiple volume sets” on page 451.

■

Options property. Use this to set the required granularity of the search: ■

roItemGranularity. Only top-level items are searched, not attachments.

roAttachmentGranularity. Both top-level items and attachments are searched. Note that the Options setting is ignored if the search uses the operator ESQfilter. See “ESQfilter searches” on page 448. ■

■

AdditionalResultsProperties property. Use this to set the required properties to be returned in results. (Use AdditionalResultsProperties in preference to the ResultsPropertySet property).

■

SortBy property. Use this to specify the required sort order of the results.

After setting the required properties, you initiate the search using the Search method. The query is passed to this method as a query string. In most cases this query string is created using the methods of ISearchQuery2 interface. The Query property returns the string that has been constructed and can be passed to the Search method. Use the Search method parameters, startResult and maximumResults to specify the number of results to return at one time. This enables you to "page" through the results. The output from a search is a pointer to a SearchResults object, which provides a structured way to access the results. The object provides standard collection support enabling iterative operations on the results in the collection, such as "for each" in Visual Basic, and .NET managed code.

Search API Using the Search API

Concurrent searches To optimize performance, applications using multiple search threads should search different archives or index volume sets.

Searching indexes that are changing during the search It is quite possible that items are being added to, or removed from, the index while a search is being performed. If this is the case, we recommend that you use the index sequence number (IndexPropertySNUM) of an item to specify the start of the batch of search results returned. The size of each batch is defined by the maximumResults parameter of the Search method. When using the index sequence number to define the batch of search results to return, do the following: ■

Always order results by increasing sequence number (IndexPropertySNUM), and ensure that the sequence number property is returned in the search results.

■

When processing a batch of search results, the highest sequence number in the results should be recorded; this should be the last one in the batch.

■

To get the next batch of results, amend the search query to return results with a sequence number (IndexPropertySNUM) greater than that recorded at the end of the previous batch of results. Repeat this until no more results are found.

Searching indexes with multiple volume sets Enterprise Vault automatically performs a federated search across multiple index volumes if the following criteria are met: ■

An index volume set is not selected using SelectIndexVolumeSet.

■

An archive has multiple index volumes, and the number of index volumes is less than, or equal to MaxSearchIndexVolumeSets (default 5).

If an archive has more than five index volumes, then you can either increase the number to be searched by setting the value of MaxSearchIndexVolumeSets, or use SelectIndexVolumeSet to select the index volume set to search. Use MaxSearchResultsPerVolumeSet to set the maximum number of results per volume set that can be processed and merged during a federated search (default is 1000). Be aware that increasing these default settings could result in a time out. If it is necessary to select a specific volume set then after calling SelectArchive, a call to IndexVolumeSets returns a collection of IIndexVolumeSet pointers from which the ID can be obtained.

451

452

Search API Using the Search API

See “IndexSearch object” on page 485.

Creating multiple index volume sets for testing In a test environment, an archive typically only has one index volume set because the number of archived items is relatively low. However, there are several properties and methods that are only tested when multiple index volume sets exist. In particular, when developing non-federated search applications, the scope for testing is very limited if there is only one index volume set available.

Processing the search results The SearchResults object is a collection of results returned by IndexSearch. (The implementation of ISearchResults2 contains a collection of ISearchResult2 interface pointers). The first result in the collection, and the maximum number of results returned in the collection are defined by the startResult and maximumResults parameters to the Search method. The SearchResults object has several properties, including the following: ■

Count. This is the number of results in the object; that is, the size of the current collection.

■

Total. This is the total number of results for the search.

You can access the data for each result returned using the methods of ISearchResult2. When searching indexes created by Enterprise Vault 10.0 or later, results include top level items only. When searching indexes created before Enterprise Vault 10.0, results may include attachments and top-level items. However, only top-level items are returned in results for these indexes if any of the following are configured: ■

Searching is limited to top-level items using roItemGranularity option in the Search method.

■

The search query includes the ESQfilter operator. Attachments are searched but the associated top-level item is returned in results.

■

The ItemGranularityOnly index schema was enabled when the index was created. Attachments are searched but the associated top-level item is returned in results.

Remember, a search result is not the archived item; it is a set of properties containing information about the item. To retrieve the archived item, use the Get method of the IItem interface in the ContentManagementAPI. See “IItem :: Get” on page 194.

Search API Using the Search API

To access the properties of each result, use the Prop method of the SearchResult class, specifying the required property as the parameter.

Enterprise Vault index properties See “System properties” on page 596. When using the Search API, Enterprise Vault property names are defined as constants in the form IndexPropXXXX. See “Index Property constants” on page 457. There are Enterprise Vault system properties and custom properties. Custom properties are typically defined and added as items are archived by third-party components using the APIs and plug in points provided by Enterprise Vault. Properties are defined as searchable, or retrievable or both: ■

Searchable means that the property can be used in search queries to find items in the archive index.

■

Retrievable means that the property can be returned in search results.

Custom properties can be referenced using propertySet.propertyName, with propertySet empty for the global property set. When searching using date search criteria, the date range values that can be returned in search results are limited to the UTC date range 1st January 1970 to 1st January 2038. Items that are indexed with dateTime properties earlier than 1 Jan 1970 are returned in the index search results, but the retrieved date values defaults to 1 Jan 1970. Items that are indexed with dateTime properties later than 1 Jan 2038 are also returned in the index search results, but the retrieved date values defaults to 1 Jan 2038. 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.

Search API example Shown here are two methods that demonstrate a search. The first method, SearchArchive, takes an archive Id and the maximum number of search results as parameters. SearchArchive compares the number of Index Volume Sets in the archive against the value of the property IIndexSearch2::MaxSearchIndexVolumeSets to determine whether a federated or non-federated search is required.

453

454

Search API Using the Search API

The second method, DoSearch, is then called. DoSearch takes two parameters: the IndexSearch2 object created in SearchArchive, and the maximum number of search results. If the search is not a federated search, this second parameter is zero. void SearchArchive(string archId, int maxSearchResults) { IIndexSearch2 search = (IIndexSearch2) new IndexSearch2(); //First select the archive search.SelectArchive(archId); //although the prefered approach is to do a non-federated search this sample //code will demonstrate both non-federated and federated //first get the IndexVolumeSets for the archive IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets; long count = volSets.Count; //use this count value to see which approach to take if (count > search.MaxSearchIndexVolumeSets) { //do non-federated search foreach (IIndexVolumeSet volSet in volSets) { search.SelectIndexVolumeSet(volSet.Identity); DoSearch(search, 0); } } else { DoSearch(search, maxSearchResults); } Marshal.FinalReleaseCOMObject(search); }

The DoSearch method, called from "SearchArchive" performs the actual search on the entire archive, or the specifed Index Volume Set, depending on whether or not the search is a federated search. The search will filter on a range of archived dates, a phrase in the subject, greater than zero attachments and the author.

Search API Using the Search API

The retrieved properties are created date, content (first 150 characters only), saveset Id, number of attachments, subject, TO:recipient, CC:recipient, BCC:recipient. Typically the property values in the query would be supplied using a GUI or a command line. However, for the purposes of this example, they are supplied in the code. void DoSearch(IIndexSearch2 search, int maxSearchResults) { ISearchQuery2 query = (ISearchQuery2) new SearchQuery2(); DateTime dtFrom = new DateTime(2007, 1, 1); DateTime dtTo = new DateTime(2007, 12, 31); query.SetRange("adat", dtFrom, dtTo, (int)ESearchQueryFlags.ESQany); query.AddRange("natc", 0, 10000, (int)ESearchQueryFlags.ESQany); query.AddTerm("subj", "a phrase in the subject", (int)ESearchQueryFlags.ESQphrase); query.AddTerm("auth", "joe.user", (int)ESearchQueryFlags.ESQexact); query.AddOp((int)ESearchQueryOperators.ESQand, 4); search.SortBy = "snum";

//if this is a federated search then set the maximum number of search //results per index volume set //if this is not a federated search then "maxSearchResults" will be 0 and //MaxSearchResultsPerVolumeSet" will not be used. if (maxSearchResults > 0) search.MaxSearchResultsPerVolumeSet = maxSearchResults; //we are going to search top level items only search.Options = (int)EOptionsFlags.roItemGranularity; //As the preferred method is to explicitly state which properties to //retrieve, first set IIndexSearch2::ResultsPropertySet to Empty. search.ResultsPropertySet = (int)EPropertySet.psEmpty; search.AdditionalResultsProperties = "date ssid natc subj cont reto recc rbcc"; int start = 1; //this is the index number into the results from which to start returning the result set

455

456

Search API Using the Search API

int count = 0; ISearchResults2 results = null; do { results = (ISearchResults2)search.Search(query.Query, start, 500, ""); if (results.InSync == true) { if (results.TruncationReason == ETruncationReason.trNone) { //make sure that date time properties are returned as local //system time not UTC results.DateTimesUTC = false; foreach (ISearchResult2 result in results) { DateTime createdDate = (DateTime)result.Prop("date"); string ssid = (string)result.Prop("ssid"); int numAttach = (int)result.Prop("natc"); string subj = (string)result.Prop("subj"); string reto = (string)result.Prop("reto"); string rbcc = (string)result.Prop("rbcc"); //do something with the results } } else { ETruncationReason tr = (ETruncationReason)results.TruncationReason; switch (tr) { case ETruncationReason.trAdminResultLimitExceeded: //do something break; case ETruncationReason.trAdminTimeoutExpired: //do something break; case ETruncationReason.trItemsOrContentMissing: //do something break;

Search API Constants and enumerations

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

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

Index Property constants When using the Search API, Enterprise Vault property names are defined as constants, where IndexPropXXXX is the constant for the property name, xxxx. See Table A-1 on page 596.

457

458

Search API Constants and enumerations

For example, IndexPropSUBJ is the constant for the Enterprise Vault defined property, "subj", and IndexPropRCAT is the constant for the Enterprise Vault system property, "rcat".

ESearchQueryFlags enumeration ESearchQueryFlags specify how to process individual terms added to a search query (for example, using AddTerm). Note: From Enterprise Vault 10.0, the Search API will not support the following search operators for newly indexed items: ESQBeginany

begins with any of

ESQBegins

begins with phrase

ESQExactany

is exactly any of

ESQEndsany

ends with any of

ESQEnds

ends with phrase

ESQAutowild

automatically add wildcard to end of all words

Using these search operators against items that were indexed using Enterprise Vault 9.0 or earlier will continue to be supported. enum ESearchQueryFlags { // Exactly one of these must be present (default is ESQany) ESQany = 0, // Contains any of the words ESQall = 1, // Contains all the words ESQallnear = 2, // Contains all the words, near each other (within 10 words) ESQphrase = 3, // Contains all the words, in order (a phrase) ESQexact

= 7, // Field exactly matches all the words, in order

ESQmatchmask = 15, // Mask to isolate above values from flags below // Zero or more of the following may be present ESQrank = 64, // Use words for results ranking ESQutcdate

=128, //Datetime should be interpreted as UTC rather than local

Search API Constants and enumerations

ESQusermask };

= 1048575 // User must not set bits outside this mask

By default, indexes are built so that they do not support case sensitive searching. This is to minimize the index storage footprint. The specified operator applies to the terms or ranges already present in the object, using a Reverse Polish scheme. Conceptually, the specified number of terms is removed from the query, and replaced with the result of combining all the terms with the specified operator. This result can then be combined with other terms or intermediate results by a subsequent AddOp method.

ESearchQueryOperators enumeration ESearchQueryOperators specify the operator to use. These operators can be used with the AddOp, Combine and AddQuery methods. enum ESearchQueryOperators { ESQand = 0, ESQor = 1, ESQandnot = 2, ESQfilter = 3 };

Using ESQfilter will only return hits on top-level documents. The search finds items that match the first query and which also match, or have a cover note or attachment that matches, all the other queries.

ESearchOperatorScope enumeration ESearchOperatorScope defines the number of operands on which an operation is to be performed. enum ESearchOperatorScope { ESQdefault = 0, ESQscopeall = 1, ESQbinary = 2, ESQternary = 3 };

If no value is given, the default is for the operator to be binary (two operands). The ESearchOperatorScope is a useful extension to the "Reverse Polish" scheme used by the AddOp method, enabling a single operator to have more than two

459

460

Search API Constants and enumerations

operands. For more than three operands, there are no symbolic constants, so the required number should be specified. Note the value of the scope is the number of operands, not the number of operations (which, when thinking of conventional binary operators, would be one less than the number of operands).

EOptionsFlags enumeration EOptionsFlags defines the granularity of searches. enum EOptionsFlags { roItemGranularity = 0x00000000,// default roAttachmentGranularity = 0x00000001, };

This setting is ignored if the search uses the operator ESQfilter. Using roItemGranularity, only top-level items are searched (not attachments). Using roAttachmentGranularity, both top-level items and attachments are searched.

EPropertySets enumeration EPropertySets are the predefined property sets that can be requested in search results. As the predefined property sets may change at future releases, we recommend that you set this property to 0 (psEmpty) and use IIndexSearch2 :: AddAdditionalResultsProperty and IIndexSearch2 :: AddAdditionalResultsCustomProperty to set the required properties to be returned in the results set. See “IIndexSearch2 :: AddAdditionalResultsProperty” on page 517. See “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 518. enum EPropertySets { psEmpty = 0, psWABrief = 1, default psWAMedium = 2, psWAFull = 3, psAEMailbox = 4, psAEFSA = 5, psAESPS = 6,

Search API Constants and enumerations

psAEMultiFolders = 7, psCompliance = 8, psItemIds = 9,// Min set of ids needed to retrieve the item. psAEShared = 10, psAEJournal = 11, psAEPublicFolder = 12, psAESharePoint = 13 };

ETruncationReason enumeration ETruncationReason explains why not all search results have been returned. enum ETruncationReason { trNone = 0, trResultLimitExceeded = 1, trTimeoutExpired = 2, trAdminResultLimitExceeded = 4, trAdminTimeoutExpired = 8, trNotSearchedOrFailedVolumes = 16, trItemsOrContentMissing = 32, trWidthNormalizationRequired = 64 }; trNotSearchedOrFailedVolumes applies to federated searches only. The index

contents for the whole archive cannot be listed. This can occur when one or more of the index volume sets are in a failed state; they could be, for example, offline or corrupt. trItemsOrContentMissing indicates that index entries are missing for items or

content in archive. trWidthNormalizationRequired is set for old indexes where character width

normalization was not applied to East Asian languages. See http://www.symantec.com/docs/TECH52355.

EXMLResultsFormatOptions enumeration EXMLResultsFormatOptions enumerates the XML format option values. Currently there is only one value: enum EXMLResultsFormatOptions {

461

462

Search API SearchQuery object

xoNone = 0x00000000// default };

SearchQuery object The SearchQuery object implements the following interfaces: ■

ISearchQuery

■

ISearchQuery2 (default)

These interfaces are used to build up a search query. Some additional methods have been introduced in ISearchQuery2, which inherits from ISearchQuery. You need to get a pointer to an instance of ISearchQuery2, as this is marked as the default.

Syntax interface ISearchQuery2 : ISearchQuery : IDispatch

Member summary Table 7-1

SearchQuery properties

Property

Read/Write

Description

ISearchQuery :: Query

Read/Write

The search query string.

Table 7-2

SearchQuery methods

Method

Description

ISearchQuery :: Clear

Discards the query currently being constructed in the object (if any), and resets the object so that it is ready for a new query.

ISearchQuery :: SetTerm

Implements Clear, followed by AddTerm.

ISearchQuery :: AddTerm

Adds a search term to the query.

ISearchQuery :: SetRange

Implements Clear followed by AddRange.

ISearchQuery :: AddRange

Adds a date or integer range to the query.

Search API SearchQuery object

Table 7-2

SearchQuery methods (continued)

Method

Description

ISearchQuery :: SetProperty

Implements Clear followed by AddProperty.

ISearchQuery :: AddProperty

Adds a property to the query.

ISearchQuery :: AddOp

Adds an operation to the query.

ISearchQuery :: Combine

Combines two search queries with an operator.

ISearchQuery :: AddQuery

Similar to combine, but combines a query with the query already in the object.

ISearchQuery2 :: Equivalent of SetRange method. Enables use of date and integer ranges SetPropertyRange for custom properties in queries. ISearchQuery2 :: Custom property equivalent of AddRange method. Enables use of date AddPropertyRange and integer ranges for custom properties in queries.

Remarks As these interfaces are ultimately derived from IDispatch, they can be used by scripting languages. Use the methods to create a query that can be used to search the index of an archive, and return the values of specified properties as results. A query consists of a number of terms, combined with different operators. The Query property enables the query to be returned as a string (so that it can then be used by the Search method), or to be set using a text string. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. 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.

Requirements See “Programming notes” on page 56.

463

464

Search API ISearchQuery :: Query

CLSID

B94D399B-B815-11D1-90D2-0000F87A3B5E

Prog ID

EnterpriseVault.IndexSearch

Type Library

EVIndexClient

DLL

IndexClient.dll

.NET Primary Interop Assembly (PIA)

KVS.EnterpriseVault.Interop.Indexclient.dll

.NET PIA namespace

KVS.EnterpriseVault.Interop

Example The object "query" constructed here will be used in the most of the following examples. It is shown here as a private class data member. [C#] public class SampleSearchClass { private ISearchQuery2 query = (ISearchQuery2) new SearchQuery(); //rest of the class

ISearchQuery :: Query The Query property is the default property. It returns a string containing the query previously constructed. The property is read/write.

Syntax HRESULT Query([out, retval] BSTR* pbsQuery); HRESULT Query([in] BSTR bsQuery);

Parameters [out, retval] BSTR* pbsQuery

Pointer to a string (BSTR) that will contain the query held in this object.

Search API ISearchQuery :: Clear

[in, string] BSTR bsQuery

String (BSTR) containing the query with which to initialize the object.

Remarks This property returns the query string that has been constructed using the other ISearchQuery2 methods.

Return value rvS_OK

Success.

Example This method is often used in conjunction with IIndexSearch2::Search where it provides the value for the first parameter, the search query. [C#] ISearchResults2 results2 = (ISearchResults2)search.Search(query.Query,

1, 100, "");

ISearchQuery :: Clear This method discards the query currently being constructed in the object (if any), and resets the object so that it is ready to build a new query.

Syntax HRESULT Clear([out, retval] BSTR* pbsQuery);

Parameters [out, retval] BSTR* pbsQuery

A pointer to a string (BSTR) that contains the contents of the query string before it was cleared out.

Remarks Clears out the string containing the query that has been constructed so far.

465

466

Search API ISearchQuery :: SetTerm

Return value rvS_OK

Success.

Example In this example the previous query is stored in the string "oldQuery". [C#] //save the query that is being cleared out string oldQuery = query.Clear();

ISearchQuery :: SetTerm This method is used to clear the current query object, reset it and add a new term (property) to the query. This is equivalent to calling the Clear method and then calling the AddTerm method.

Syntax HRESULT SetTerm([in, string] const BSTR bsProp, [in] VARIANT vVal, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters [in, string] const BSTR bsProp

The name of the property to be searched for.

[in] VARIANT vVal

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

[in, defaultvalue(0)] const long lFlags

Search Query Flags that define how to process the terms added to the search query. See “ESearchQueryFlags enumeration” on page 458.

Search API ISearchQuery :: SetTerm

Pointer to a string (BSTR) that contains the current value of the query string after this method has returned.

[out, retval] BSTR* pbsQuery

Remarks If the bsProp parameter is left empty, then all indexed properties are searched for the value. This is really only useful for string values. The parameter lFlags must contain one ESearchQueryFlags enumeration value. This value may be bitwise OR'd (C++ operator "|") with one or more values from the extended values. bsProp can be a custom index property that has been added using the Content Management API, or one of the Filtering APIs. This would be specified using the format: propertySet.propertyName

If the custom index property is a member of the global property set, then the property set name is omitted. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. 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.

Return value rvS_OK

Success.

Example In this example a query is constructed that will find all items where the subject contains the phrase "some subject", and the number of attachments is 1. In this example the return value is not used. [C#] //search for an item where the subject contains the phrase

"some subject"

query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase);

467

468

Search API ISearchQuery :: AddTerm

//search for an item with 1 attachment query.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany); //now we AND the 2 terms so that both terms must be satisfied before returning a result query.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);

See also ■

See “ISearchQuery :: AddTerm” on page 468.

■

See “System properties” on page 596.

■

See “SimpleIndexMetadata object” on page 256.

ISearchQuery :: AddTerm This method is used to add a new term (property) to the query.

Syntax HRESULT AddTerm([in, string] const BSTR bsProp, [in] VARIANT vVal, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters Table 7-3

AddTerm method parameters

Parameter

Description

[in, string] const BSTR bsProp

The name of the property in which to search for the value.

[in] VARIANT vVal

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

[in, defaultvalue(0)] const long lFlags

Search Query Flags that define how to process the terms added to the search query. See “ESearchQueryFlags enumeration” on page 458.

Search API ISearchQuery :: AddTerm

Table 7-3

AddTerm method parameters (continued)

Parameter

Description

[out, retval] BSTR* pbsQuery

Pointer to a string that contains the current value of the query string after this method has returned.

Remarks If the bsProp parameter is left empty, all indexed properties are searched for the value. This is really only useful for string values. The parameter lFlags must contain one ESearchQueryFlags enumeration value. This value may be bitwise or'd (C++ operator "|") with one or more values from the extended values. bsProp can be a custom index property that has been added using the Content Management API, or one of the Filtering APIs. This would be specified using the format: propertySet.propertyName

If the custom index property is a member of the global property set, then the property set name is omitted. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. 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.

Return value rvS_OK

Success.

Example In this example, a query is constructed that finds all items where the subject contains the phrase "some subject" and the number of attachments is 1. The return value is not used. [C#]

469

470

Search API ISearchQuery :: SetRange

//search for an item where the subject contains the phrase "some subject" query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase); //search for an item with 1 attachment query.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany); //now we AND the two terms so that both terms must be satisfied before returning a result query.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);

See also ■

See “System properties” on page 596.

■

See “SimpleIndexMetadata object” on page 256.

■

See “ISearchQuery :: SetTerm” on page 466.

■

See “ISearchQuery :: AddProperty” on page 476.

ISearchQuery :: SetRange This method is used to delete all queries in the query object, reset the object and add a date or numeric (integer) range to the query being built in the object. This is equivalent to calling Clear then AddRange.

Syntax HRESULT SetRange([in, string] const BSTR bsProp, [in] VARIANT vVal1, [in] VARIANT vVal2, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters [in, string] const BSTR bsProp

The name of the property in which to search for the value.

[in] VARIANT vVal1

The first value in the range. This can be date or integer.

[in] VARIANT vVal2

The last value in the range. This can be date or integer.

Search API ISearchQuery :: SetRange

[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 contains the current value of the query string after this method has returned.

Remarks 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. This method can only be used with date or integer values. When specifying dateTime values, it is strongly recommended that you set ESearchQueryFlags.ESQutcdate and supply UTC dateTime values. If ESearchQueryFlags.ESQutcdate is not set, dateTime values are treated as local system dateTime. bsProp can be a custom index property that has been added using the Content Management API, or one of the Filtering APIs. This would be specified using the format: propertySet.propertyName

If the custom index property is a member of the global property set, then the property set name is omitted. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. 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.

Return value rvS_OK

Success.

471

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, or that have less than five attachments. //search for all items archived between 01/01/2008 and 31/10/2008 inclusive DateTime from = new DateTime(2008, 1, 1, 0, 0, 0, DateTimeKind.Utc); DateTime to = new DateTime(2008, 10, 31, 23, 59, 59, DateTimeKind.Utc); query.SetRange("adat",

from,

to, (

int)(ESearchQueryFlags.ESQany | ESearchQueryFlags.ESQutcdate)); //search for items with less than 5 attachments query.AddRange("natc", 0, 4, (int)ESearchQueryFlags.ESQany); //OR the 2 terms together so the result set will contain items that fall into one or //the other (or both) ranges query. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);

See also ■

See “ISearchQuery :: AddRange” on page 472.

■

See “System properties” on page 596.

■

See “SimpleIndexMetadata object” on page 256.

ISearchQuery :: AddRange This method is used to add a date or numeric integer range to the query being built in the object.

Syntax HRESULT AddRange([in, string] const BSTR bsProp, [in] VARIANT vVal1, [in] VARIANT vVal2, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters [in, string] const BSTR bsProp

The name of the property in which to search for the value.

[in] VARIANT vVal1

The upper or lower boundary of the range. This can be date or integer.

Search API ISearchQuery :: AddRange

[in] VARIANT vVal2

The upper or lower boundary of the range. This can be date or integer.

[in, defaultvalue(0)] const long lFlags

Search Query Flags that define how to process the range added to the search query. See “ESearchQueryFlags enumeration” on page 458.

[out, retval] BSTR* pbsQuery

Pointer to a string that contains the current value of the query string after this method has returned.

Remarks This method can only be used with date/time or integer values. 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. When specifying dateTime values, it is strongly recommended that you set ESearchQueryFlags.ESQutcdate and supply UTC dateTime values. If ESearchQueryFlags.ESQutcdate is not set, dateTime values are treated as local system dateTime. bsProp can be a custom index property that has been added using the Content Management API, or one of the Filtering APIs. This would be specified using the format: propertySet.propertyName

If the custom index property is a member of the global property set, then the property set name is omitted. There are restrictions on the date range that can be returned in search results. See “Enterprise Vault index properties” on page 453. 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.

473

474

Search API ISearchQuery :: SetProperty

Return value rvS_OK

Success.

Example This example builds a query that will find items archived between 01/01/2008 and 21/10/2008 inclusive, or that have less than five attachments. [C#] //search for all items archived between 01/01/2008 and 31/10/2008 inclusive DateTime from = new DateTime(2008, 1, 1); DateTime to = new DateTime(2008, 10, 31); query.SetRange("adat", from, to, (int)ESearchQueryFlags.ESQany); //search for items with less than 5 attachments query.AddRange("natc", 0, 4, (int)ESearchQueryFlags.ESQany); //OR the 2 terms together so the result set will contain items that fall into one //or the other (or both) ranges query. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);

See also ■

See “ISearchQuery :: SetRange” on page 470.

■

See “System properties” on page 596.

■

See “SimpleIndexMetadata object” on page 256.

ISearchQuery :: SetProperty This method clears all queries from the query object, resets the object, and adds a custom property that can be used for searching. This is equivalent to calling Clear then AddProperty.

Syntax HRESULT SetProperty([in, string] const BSTR bsPropSet, [in, string] const BSTR bsProp, [in] VARIANT vVal, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Search API ISearchQuery :: SetProperty

Parameters [in, string] const BSTR bsPropSet

Name of the property set.

[in, string] const BSTR bsProp

The name of the custom property to search for.

[in] VARIANT vVal

VARIANT containing value to search for. This can be a string, date or integer.

[in, defaultvalue(0)] const long lFlags

Search Query Flags that define how to process the range added to the search query. See “ESearchQueryFlags enumeration” on page 458.

[out, retval] BSTR* pbsQuery

Pointer to a string containing the query as it stands after this method returns.

Remarks Note that SetTerm can also be used to set a term for a custom property using the propertySet.propertyName format. SetProperty method is very similar to SetTerm, but as it requires both a property set and property name, it can only be used to add custom properties.

Return value rvS_OK

Success.

Example It is assumed that a custom property "Type", belonging to the property set "Instrument", has been added to archived items. Two queries are constructed in this sample; the first searches for all queries with the custom property Instrument.Type = ‘Guitar’. The second searches for all items where the retention category = ‘Business’. The two queries are combined to form one query that searches for all items where Instrument.Type is ‘Guitar’ and retention category is not ‘Business’.

475

476

Search API ISearchQuery :: AddProperty

[C#] //search for items with custom property value ‘Guitar’ string qry1 = query.SetProperty("Instrument", "Type", "Guitar", (int) ESearchQueryFlags.ESQexact); //search for items with a retention category of "Business" string qry2 = query.SetTerm("rcat", "Business", (int)(ESearchQueryFlags.ESQexact); //combine the 2 queries so that the result set contains items that contain ‘Guitar’ in //the custom property Instrument.Type and that have a retention category that is not //‘Business’ query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot);

See also ■

See “ISearchQuery :: SetTerm” on page 466.

■

See “ISearchQuery :: AddProperty” on page 476.

■

See “System properties” on page 596.

■

See “SimpleIndexMetadata object” on page 256.

ISearchQuery :: AddProperty This method adds a custom property to the query being built in the object and which can be used for searching.

Syntax HRESULT AddProperty([in, string] const BSTR bsPropSet, [in, string] const BSTR bsProp, [in] VARIANT vVal, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters [in, string] const BSTR bsPropSet

Name of the property set.

[in, string] const BSTR bsProp

The name of the custom property to search for.

Search API ISearchQuery :: AddProperty

[in] VARIANT vVal

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

[in, defaultvalue(0)] const long lFlags

Search Query Flags that define how to process the range added to the search query. See “ESearchQueryFlags enumeration” on page 458.

[out, retval] BSTR* pbsQuery

Pointer to a string containing the query as it stands after this method returns.

Remarks This method is very similar to AddTerm, but with both a property set and property name being included as parameters. This means that it can only be used to add custom properties.

Return value rvS_OK

Success.

Example In this example we use the return value which holds the current query. It is also assumed that a custom property "Type", belonging to the property set "Instrument", has been added to archived items as well as a custom property "Colour", belonging to the same property set. The example builds two queries; the first searches for all items where Instrument.Colour is ‘Red’. The second searches for items where Instrument.Type is ‘Guitar’. The two queries are combined to form one, in order to search for all items where Instrument.Type is ‘Guitar’ and Instrument.Colur is ‘Red’. [C#] //search for items where custom property Instrument.Colour = "Red" string qry1 = query.SetProperty("Instrument", "Colour", "red", (int)ESearchQueryFlags.ESQexact); //search for items with custom property Instrument.Type = ‘Guitar’ string qry2 = query.AddProperty("Instrument", "Type", "Guitar", (int)( ESearchQueryFlags.ESQexact);

477

478

Search API ISearchQuery :: AddOp

//combine the 2 queries so that the result set contains items that contain ‘Guitar’ in //the custom property Instrument.Type and "red" in Instrument.Colour" query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQand);

See also ■

See “ISearchQuery :: AddTerm” on page 468.

■

See “ISearchQuery :: SetProperty” on page 474.

■

See “System properties” on page 596.

■

See “SimpleIndexMetadata object” on page 256.

ISearchQuery :: AddOp This method is used to add an operator to the query in order to combine previously defined terms.

Syntax HRESULT AddOp([in] const long lOp, [in, defaultvalue(0)] const long lScope, [out, retval] BSTR* pbsQuery);

Parameters [in] const long lOp

The operator to use. See “ESearchQueryOperators enumeration” on page 459.

[in, defaultvalue(0)] const long lScope

How the operator is to be applied. See “ESearchOperatorScope enumeration” on page 459.

[out, retval] BSTR* pbsQuery

Pointer to string that will contain the value of the query after this operator has been added.

Remarks This method combines the previous x properties by using the operator defined in the first parameter, where x is the value given in the second parameter.

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

492

Search API IIndexSearch2 :: SortBy

The property is read/write.

Syntax HRESULT SortBy([in] BSTR sortProperties, [out,retval] BSTR* sortProperties);

Parameters [in] BSTR sortProperties

String containing the properties by which to sort search results.

[out,retval] BSTR* sortProperties

Pointer to a string that will contain the current properties used for sorting.

Remarks sortProperties can be none or one index property. The sort order is normally ascending, but you can reverse the order by preceding the property with a minus sign (-), for example: search.SortBy = "-" + "adat";

Return value rvS_OK

Success.

rvE_POINTER

The pointer passed in to receive the current value is invalid.

Example This example shows how to sort by archived date, in descending order. [C#] [in] //sort by archived date descending search.SortBy = "-" + "adat"; [out] string sortBy = search.SortBy;

Search API IIndexSearch2 :: ResultsPropertySet

IIndexSearch2 :: ResultsPropertySet This property can be used to specify a predefined set of properties returned in search results. See Remarks for important comments on using this property. The property is read/write.

Syntax HRESULT ResultsPropertySet([in] long propertySet, [out,retval] long* propertySet);

Parameters [in] long propertySet

Long integer containing the EPropertySets value to be set. See “EPropertySets enumeration” on page 460.

[out,retval] long* propertySet

Pointer to a long integer that will receive the current value.

Remarks As the predefined property sets may change in future releases, we strongly recommend that you set this property to psEmpty, and use the AdditionalResultsProperties property and/or AddAdditionalResultsProperty and AddAdditionalResultsCustomProperty to set the required properties to be found in the result set.

Return value rvS_OK

Success.

rvE_POINTER

The long pointer passed in to receive the current value is invalid.

rvE_INVALIDARG The value being set is less than 0.

Example As this property is no longer the recommended way of setting the returned properties, it is set to "empty".

493

494

Search API IIndexSearch2 :: AdditionalResultsProperties

[C#] [in] search.ResultPropertySet = (int)EPropertySets.psEmpty; [out] if (search.ResultPropertySet != 0) { search.ResultPropertySet = 0; // (psEmpty) }

See also ■

See “IIndexSearch2 :: AdditionalResultsProperties” on page 494.

■

See “IIndexSearch2 :: AddAdditionalResultsProperty” on page 517.

■

See “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 518.

IIndexSearch2 :: AdditionalResultsProperties This property is the recommended way to define the properties returned in search results. The property is read/write.

Syntax HRESULT AdditionalResultsProperties([in] BSTR propertiesList); HRESULT AdditionalResultsProperties([out,retval] BSTR* propertiesList);

Parameters [in] BSTR propertiesList

String containing a space separated list of properties to be returned in the search results.

[out,retval] BSTR* propertiesList

Pointer to a string that will receive a list of the current properties.

Remarks The properties added must be in the format of a space delimited list.

Search API IIndexSearch2 :: Timeout

Properties you define using this property should be in addition to those found in the predefined property sets. It is recommended that the empty ResultPropertySet is selected. See “EPropertySets enumeration” on page 460.

Return value rvS_OK

Success.

rvE_POINTER

The string pointer passed in to receive the current value is invalid.

Example Note that as IIndexSearch2::ResultPropertySet is no longer a preferred method, it is set "empty" as a precaution. [C#] [in] search.ResultPropertySet = (int)EPropertySets.psEmpty; //set empty search.AdditionalResultsProperties = "ssid adat natc"; [out] string props = search.AdditionalResultsProperties; if (props.Contains("ssid")) { //do something

See also ■

See “IIndexSearch2 :: AddAdditionalResultsProperty” on page 517.

■

See “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 518.

■

See “IIndexSearch2 :: ResultsPropertySet” on page 493.

IIndexSearch2 :: Timeout This property defines the timeout period applied to search requests. The property is read/write.

495

496

Search API IIndexSearch2 :: Timeout

Syntax HRESULT Timeout([in] long seconds, [out,retval] long* seconds);

Parameters Long integer containing number of seconds to wait before the search times out. The default value is 120 seconds.

[in] long seconds

[out,retval] long* seconds Pointer to a long integer that will receive the current value.

Remarks For searches on indexes created using Enterprise Vault 9.0 or earlier, the timeout period is only applied to federated search requests (that is, searches across multiple index volume sets). For searches on indexes created using Enterprise Vault 10.0 or later, the timeout period is applied to all search requests.

Return value rvS_OK

Success.

rvE_POINTER

The new value being set is equal to or less than zero.

rvE_INVALIDARG

The long integer pointer passed in to receive the current value is incorrect.

Example [C#] [in][out] if (search.Timeout < 120) { search.Timeout = 120; }

Search API IIndexSearch2 :: ArchiveEntryId

IIndexSearch2 :: ArchiveEntryId This property returns the ID of the archive that is currently selected for searching. The property is read only.

Syntax HRESULT ArchiveEntryId([out,retval] BSTR* value)

Parameters [out,retval] BSTR* value

Pointer to a string that will receive the current value.

Remarks This method will only return a valid Id after SelectArchive has been called.

Return value rvS_OK

Success.

rvE_POINTER

The BSTR pointer passed in to receive the current value is invalid.

rvS_FALSE

The archive has not been selected yet.

Example [C#] search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"); //do something string aeid = search.ArchiveEntryId;

IIndexSearch2 :: ArchiveName This property returns the name of the archive that is currently selected for searching. The property is read only.

497

498

Search API IIndexSearch2 :: HasFolders

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

Parameters [out,retval] BSTR* value

Pointer to a string that will contain the current value.

Remarks This method will only return a valid archive name after SelectArchive has been called. If the archive has not been selected, then the return value will be S_FALSE. If tested in one of the C++ SUCCEEDED or FAILED macros, this will register as true. It is therefore advisable to test that the value acquired is as expected.

Return value rvS_OK

Success.

rvE_POINTER

The BSTR pointer passed in to receive the current value is invalid.

rvS_FALSE

The archive has not been selected.

Example [C#] search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"); //display the archive name in a textbox. textBoxArchId.Text = search.ArchiveName;

IIndexSearch2 :: HasFolders This property indicates whether the currently selected archive contains a folder structure. The property is read only.

Search API IIndexSearch2 :: IndexVolumeSetIdentity

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

Parameters [out,retval] VARIANT_BOOL* value

Pointer to a VARIANT_BOOL that will receive the current value.

Remarks This method will only return a valid result after SelectArchive has been called.

Return value rvS_OK

Success.

rvE_POINTER

Value is an invalid pointer.

rvS_FALSE

The archive has not been selected.

Example [C#] search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"); //do something if (search.HasFolders == true) { //do something

IIndexSearch2 :: IndexVolumeSetIdentity This property identifies the volume set of the index volume to search. The property is read only.

Syntax HRESULT IndexVolumeSetIdentity([out,retval] long* value);

499

500

Search API IIndexSearch2 :: IndexVolumeIdentity

Parameters [out,retval] long* value

Pointer to a long that will receive the current value.

Remarks This property will return a valid Id after SelectArchive has been called. It returns -1 and S_FALSE if SelectArchive has not been called, or the selected archive has multiple index volume sets and SelectIndexVolumeSet has not been called.

Return value rvS_OK

Success.

rvE_POINTER

The long integer pointer passed in to receive the current value is invalid.

rvS_FALSE

Either SelectArchive has not been called, or there is an invalid value for the Index Volume.

Example [C#] search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsit e1"); //do something long id = search.IndexVolumeSetIdentity; if (id == -1) MessageBox.Show("This archive has multiple Index Volume Sets please select one", "Multiple Index Volume Sets", MB_OK);

IIndexSearch2 :: IndexVolumeIdentity This property should not be used: it is currently available for Enterprise Vault internal purposes only. The property is read only.

Syntax HRESULT IndexVolumeIdentity([out,retval] long* value);

Search API IIndexSearch2 :: IndexVolumeSetCount

Parameters [out,retval] long* value

Pointer to a long integer that will hold the current value.

Remarks This property should not be used. This property returns the IndexVolumeIdentity as selected by the search application. See “IndexSearch object” on page 485.

Return value rvS_OK

Success. The IndexVolumeIdentity is valid (that is, not 0 or -1) and a valid archive has been selected.

rvS_FALSE

The archive Id has not been selected, or the internal index volume identity has not been populated (for example, in a federated search).

rvE_POINTER

Value is an invalid pointer.

IIndexSearch2 :: IndexVolumeSetCount This property returns the number of index volume sets in the archive's index. The property is read only.

Syntax HRESULT IndexVolumeSetCount([out,retval] long* value);

Parameters [out,retval] long* value Pointer to a long integer that will receive the current value.

Remarks This property should not be used before SelectArchive has been called.

501

502

Search API IIndexSearch2 :: MaxSearchIndexVolumeSets

Return value rvS_OK

Success.

rvS_FALSE

SelectArchive has not been called.

rvE_POINTER

The long integer pointer passed in to receive the current value is invalid.

Example [C#] search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1"); long count = search.IndexVolumeSetCount; //want to do a federated search depending on number of Index Volume sets if (count