+ All Categories
Home > Documents > Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault:...

Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault:...

Date post: 17-Mar-2020
Category:
Upload: others
View: 60 times
Download: 0 times
Share this document with a friend
692
Symantec Enterprise Vault Application Programmer’s Guide Enterprise Vault 9.0 SP1
Transcript
Page 1: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Symantec Enterprise Vault™

Application Programmer’s Guide

Enterprise Vault 9.0 SP1

Page 2: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Symantec Enterprise Vault: Application Programmer’s Guide

The software described in this book is furnished under a license agreement and may be used only in accordance with the terms of the agreement.

Last updated: November 19, 2010.

Legal NoticeCopyright © 2010 Symantec Corporation. All rights reserved.

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

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

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

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

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

Symantec Corporation350 Ellis StreetMountain View, CA 94043

http://www.symantec.com

Page 3: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Technical SupportIn 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

Page 4: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under
Page 5: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Contents

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

Chapter 1 About this guideIntroducing this guide .........................................................................................15Enterprise Vault documentation .......................................................................15Comment on the documentation .......................................................................15

Chapter 2 API updatesNotice of future changes .....................................................................................17Enterprise Vault 9.0 .............................................................................................18Enterprise Vault 8.0 SP5 .....................................................................................18Enterprise Vault 8.0 SP4 .....................................................................................20Enterprise Vault 8.0 SP3 .....................................................................................21Enterprise Vault 8.0 SP2 .....................................................................................23Enterprise Vault 8.0 SP1 .....................................................................................24Enterprise Vault 8.0 .............................................................................................25Enterprise Vault 7.0 SP4 .....................................................................................30Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0

SP5 ..................................................................................................................31Enterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4

33Enterprise Vault 7.0 .............................................................................................34

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

Chapter 4 Content Management APIAbout the Content Management API ................................................................49

Page 6: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

6 Contents

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

Page 7: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

7Contents

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

Page 8: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

8 Contents

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

Page 9: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

9Contents

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

Chapter 5 NSF Manager APINSF Manager API ...............................................................................................371Enumerations .....................................................................................................374NSFManager object ............................................................................................375INSFManager :: OpenNSF .................................................................................377INSFManager :: CreateNSF ...............................................................................378

Page 10: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

10 Contents

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

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

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

Page 11: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

11Contents

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

Page 12: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

12 Contents

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

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

Page 13: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

13Contents

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

Page 14: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

14 Contents

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

Appendix A About Enterprise Vault indexesAbout index volume sets and volumes ...........................................................659About index schemas ........................................................................................660

Appendix B Enterprise Vault PropertiesSystem properties ..............................................................................................664Defined custom properties ...............................................................................680Defined custom FSA properties .......................................................................681Defined custom SharePoint properties ..........................................................681Defined properties for Compliance Accelerator ...........................................682

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

Index ......................................................................................................691

Page 15: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

1

About this guide

This chapter includes the following topics:

■ “Introducing this guide”

■ “Enterprise Vault documentation”

■ “Comment on the documentation”

Introducing this guideThis 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 documentationThis 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 documentationLet us know what you like and dislike about the documentation. Were you able to find the information you needed quickly? Was the information clearly

Page 16: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

16 About this guideComment on the documentation

presented? Report errors and omissions, or tell us what you would find useful in future versions of our guides and online help.

Please include the following information with your comment:

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

■ The topic (if relevant) you are commenting on

■ Your name

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

We appreciate your feedback.

Page 17: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

2

API updates

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

Notice of future changesThis section lists significant changes to Enterprise Vault APIs in upcoming releases.

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

Search APIFrom Enterprise Vault 10, the Search API will not support the following search operators for newly indexed items:

■ begins with any of (ESQBeginany)

■ begins with phrase (ESQBegins)

■ is exactly any of (ESQExactany)

■ ends with any of (ESQEndsany)

■ ends with phrase (ESQEnds)

■ automatically add wildcard to end of all words (ESQAutowild)

Using these search operators against previously indexed items will continue to be supported.

Page 18: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

18 API updatesEnterprise Vault 9.0

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

Content Management API

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

Ref Change details

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

900-1652 Guidance on thread priority has been added.

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

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

900-2677 Added the method IItem3::Undelete.

If an item has been moved to the Enterprise Vault "dumpster" area (soft deleted), this method can be used to recover the item.

See “IItem3 :: Undelete” on page 217

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

See “IItem :: Insert” on page 196

See “IContent :: FileExtension” on page 224

See “IContent :: MIMEFormat” on page 226

Page 19: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

19API updatesEnterprise Vault 8.0 SP5

Content Management API

Filtering APIs

Enterprise Vault properties

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 138

E2133959 ISimpleIndexProperty :: Value now has a fuller description of possible values for the property.

See “ISimpleIndexProperty :: Value” on page 299

Ref Change details

8054561, E2096343

HARD_DELETE is now available as an option in the Domino action enumeration.

See “EV_ACTION enumeration” on page 433

E1980890 The following sections have been expanded to provide more information on the filtering registry settings:

See “Exchange filtering registry settings” on page 430

See “Domino filtering registry settings” on page 474

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

See “IArchivingControl2 :: MAPISaveChanges” on page 467

Ref Change details

E2027779 Added the property, Vault.CopiedFrom, to the list of custom properties defined in Enterprise Vault. This property provides details for items that have been copied by Move Archive.

See “Defined custom properties” on page 680

Page 20: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

20 API updatesEnterprise Vault 8.0 SP4

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

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

E2139819 The following index properties have been added to the list of Enterprise Vault system properties:

■ Calendar start date (csrt)

■ Calendar end date (cend)

■ Calendar location (clon)

■ Task due date (tddt)

■ Task date completed (tcdt)

■ Task status (tsts)

See “System properties” on page 664

Ref Change details

Ref Change details

E1927661 Updated IContent :: FileExtension section in the manual to clarify the when a preceding period is included in file extensions.

See “IContent :: FileExtension” on page 224

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

E1669297 The description of the EV_STG_API_ITEM_DETAIL enumeration has been expanded to show the properties that are returned for the different enumeration values.

See “EV_STG_API_ITEM_DETAIL enumeration” on page 65

804-1613, 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.

Page 21: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

21API updatesEnterprise Vault 8.0 SP3

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

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

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

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 200

Ref Change details

Ref Change details

E1448964 Information has been added to the Search API chapter on how to create multiple index volume sets for testing search applications.

See “Performing a search” on page 524

Ref Change details

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

See “IItem2 :: DeletionReason” on page 215

Page 22: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

22 API updatesEnterprise Vault 8.0 SP3

803137 Soft deleted items are no longer included when populating the Items collection object.

See “Items object” on page 162

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, E1739537

Sometimes files of between 5 MB and 50 MB were truncated when retrieved using the Content Management API .

This has been fixed.

Ref Change details

Page 23: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

23API updatesEnterprise Vault 8.0 SP2

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

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

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.

Ref Change details

Ref Change details

802168 A new interface, IExtendedErrorInfo, has been added. This interface provides extended error information if an error is encountered when using the Content Management API methods.

See “ExtendedErrorInfo object” on page 355.

802077 EV_STG_API_AUTHENTICATE_USING enumeration has new value added: AUTHENTICATE_USING_MOST_APPROPRIATE_MODE

See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 60.

802559, E1703228, E1639951

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

See “IItem :: Insert” on page 196.

802577, E1476982, E1600648

IArchive::Name and IArchive::Description can contain printable, Unicode characters.

IArchive::Name is mandatory and cannot be blank or an empty string.

IArchive::Description is optional.

See “IArchive :: Name” on page 126, and “IArchive :: Description” on page 128.

Page 24: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

24 API updatesEnterprise Vault 8.0 SP1

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

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

Ref Change details

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

See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 64

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

See “IHolds2 :: ReleaseHolds2” on page 330

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

Page 25: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

25API updatesEnterprise Vault 8.0

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

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

Changes to programming language support

Visual Basic 6.0The 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 ScriptThe 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 changesAudit logging can now be enabled for item operations.

See “Audit logging” on page 56.

The name of the Enterprise Vault SDK kit has changed toSymantec Enterprise Vault Software Development Kit.msi

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.

Ref Change details

Page 26: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

26 API updatesEnterprise Vault 8.0

The name of the Enterprise Vault API runtime kit has changed to:Symantec Enterprise Vault API Runtime.msi

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

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

Ref Change details

■ The following new interfaces have been added to the Content Management API:IContentManagementAPI3IArchive3IItemsIArchiveMetaData2

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

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

BAU0819BAU2464

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

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

Page 27: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

27API updatesEnterprise Vault 8.0

BAU0778BAU0795BAU1179

■ 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 “Specifying item property override values” on page 193.

BAU0378 ■ IArchiveMetaData2 provides additional properties for determining the archive folder location of an item:

■ The CurrentLocation or CurrentFolderId properties identify the archive folder in which the item is stored, or to be stored.

See “Which properties determine the current archive folder” on page 267.

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

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

Ref Change details

Page 28: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

28 API updatesEnterprise Vault 8.0

BAU1179BAU2853

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

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

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

BAU1796 ■ Enhancements to the API mean that .NET applications no longer need to call CoInitializeSecurity when remotely accessing IStream or IlockBytes objects containing large items (larger than 4MB).

■ The Content Management API threading model has been changed from COM single-threaded apartment (STA) to Both, thus simplifying use in .NET applications.

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

Ref Change details

Page 29: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

29API updatesEnterprise Vault 8.0

Retention API

Migration API

New index properties added

Table 2-1 Changes to Retention API

Ref Change details

BAU1072 Enabled the caller to set the date from which storage expiry is calculated.

Added the following interfaces, method and property:

■ IRetentionCategories2Improved the retrieval of retention category details by providing a Get method.

■ IRetentionCategory2Provides ExpiryBasis property for determining date from which storage expiry is calculated.

Table 2-2 Change to Migration API

Ref Change details

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

The migrator must now explicitly set this value.

Table 2-3 New index properties

Ref Index property name

Description

BAU0585 crct Current Retention Category Id, searchable and retrievable

BAU0931 clcn

cllf

clfn

crcn

Current location, retrievable only

Current leaf folder name, retrievable only

Current location folder names, retrievable only

Current Retention Category name, retrievable only

BAU1320 cnhv Conversation Hierarchical View, retrievable only

BAU1426 fpdd

fpcn

Index Fingerprint of item, searchable and retrievable

Index Fingerprint of content, searchable and retrievable

Page 30: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

30 API updatesEnterprise Vault 7.0 SP4

Corrections

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

Table 2-4 Corrections

Ref Change details

1088101, 847952

The Storage service is no longer accessed when enumerating archives.

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

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

Table 2-5 Corrections

Ref Change details

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

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

E1167957 Updated information about supported combinations of properties in “Archives object” on page 109.

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

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

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

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

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

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

Page 31: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

31API updatesEnterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5

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.

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

Table 2-5 Corrections

Ref Change details

Table 2-6 Changes and corrections

Ref Change details Availability

751207, 703021, 605047

■ New sere index property. This property returns sender and recipient details from the message header (P2) if the archived item is a message. See Table B-1 on page 664.

■ menv index property changes. This property is now only returned for journaled messages. It returns sender recipient details from the message envelope (P1) if the archived item is an envelope message. See Table B-1 on page 664.

Enterprise Vault 6.0 SP5, Enterprise Vault 7.0 SP3, Enterprise Vault 2007 SP1

751208, 703020, 605036

■ New interface for Exchange filtering, IArchvingControl3, to retrieve sender and recipient information as XML. See “IArchivingControl interface for Exchange filtering” on page 439.

Enterprise Vault 6.0 SP5, Enterprise Vault 7.0 SP3, Enterprise Vault 2007 SP1

751127, 703010

■ SimpleIndexProperty object: Added new attachment number ("anum") in the returned index data with the attachment numbering based on the attachment structure as stored in the saveset indexable item data stream. See “ISimpleIndexProperty :: Name” on page 296.

■ menv index property: This property now includes the message sender/author and delegate sender (if applicable) encoded in the <AUTH> element. See Table B-1 on page 664.

Enterprise Vault 7.0 SP3, Enterprise Vault 2007 SP1

Page 32: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

32 API updatesEnterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5

751143, 703011

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

Enterprise Vault 7.0 SP3, Enterprise Vault 2007 SP1

703038, E1143932

■ IArchive::Create: updated description of properties and examples. See “IArchive :: Create” on page 146.

Enterprise Vault 7.0 SP3, Enterprise Vault 2007 SP1

Table 2-6 Changes and corrections

Ref Change details Availability

Page 33: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

33API updatesEnterprise Vault 2007, Enterprise Vault 7.0 SP2, and Enterprise Vault 6.0 SP4

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

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

Table 2-7 Changes and corrections

Ref Change details Availability

DOR610 ■ The following new Content Management API 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.

Enterprise Vault 2007

DOR620 ■ Simple API removed from API 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.

Enterprise Vault 2007

Page 34: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

34 API updatesEnterprise Vault 7.0

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

702045, 604133, E974294

■ When the enumerated value, DETAIL_LEVEL_ITEM_CONTENT, 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.

Enterprise Vault 6.0 SP4, Enterprise Vault 7.0 SP2

702045, 604133

■ In previous releases, you could not retrieve expanded distribution list information from the XMLStream using the Content Management API.This information can now be accessed using the existing IArchiveMetaData :: IndexData property. It is retrieved in the menv index property using the DETAIL_LEVEL_MESSAGE_ENVELOPE_INDEXDATA value of the EV_STG_API_ITEM_DETAIL enumeration. Note that MSXML 4.0 is required for this feature.See “EV_STG_API_ITEM_DETAIL enumeration” on page 65.The menv index property is described in Table B-1 on page 664.

■ The value of ISimpleIndexProperty :: Name can now be a formatted number (1, 1.1, 1.2 and so on), which refers to a message attachment.See “ISimpleIndexProperty :: Name” on page 296.

Enterprise Vault 6.0 SP4, Enterprise Vault 7.0 SP2

Table 2-7 Changes and corrections

Ref Change details Availability

Table 2-8 Changes and corrections

Ref Change details Availability

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

Page 35: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

35API updatesEnterprise 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 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.

Enterprise Vault 7.0

CAP545, CAP721, E804597

■ IArchivingControl2 interface 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.

Enterprise Vault 7.0

CAP525

E775452

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

Enterprise Vault 7.0

Table 2-8 Changes and corrections

Ref Change details Availability

Page 36: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

36 API updatesEnterprise Vault 7.0

Page 37: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

3

Enterprise Vault API overview

This chapter introduces the Enterprise Vault SDK and the APIs it comprises. These can be used by applications to access Enterprise Vault functionality.

Overview of Enterprise Vault APIsEnterprise Vault SDK comprises a number of APIs. The various Enterprise Vault APIs are implemented as COM or .NET objects, which expose task-specific interfaces. For example, archiving items uses the IContentMangementAPI and IItem interfaces.

In general, applications which use the APIs should be run from a client computer, and not on the Enterprise Vault server.

Page 38: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

38 Enterprise Vault API overviewOverview of Enterprise Vault APIs

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

Table 3-1 Enterprise Vault APIs

Content Management API ■ Create archives.

■ Enumerate collections of vault stores, archives or items.

■ Get properties of vault stores and archives.

■ List the items in an archive.

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

■ Get item properties.

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

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

■ Remove any holds placed on items. (Legal Hold)

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

NSF Manager API Enables interaction between Enterprise Vault and Notes databases:

■ Extract notes from an archive using the Enterprise Vault Content Management API, and import them into a database

■ Extract notes from a database and place them in an Enterprise Vault archive

■ Create and delete databases

Search API ■ Search Enterprise Vault indexes.

Retention API ■ Create new retention categories.

■ Enumerate retention categories.

■ Set locks on a retention category.

■ Update an existing retention category.

■ Look up an existing retention category.

Page 39: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

39Enterprise Vault API overviewPrerequisite software and settings

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

Prerequisite software and settingsDetails 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.

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

Exchange Filtering API

Domino Filtering API

External filters enable preprocessing of items in order to decide on the actions to take; for example, whether to archive the item and which archive settings to apply.

The Filtering APIs provide the ability to:

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

■ Store selected items in specific archives.

■ Set a particular retention category on selected items.

■ Delete selected items without archiving them.

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

Table 3-1 Enterprise Vault APIs

Page 40: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

40 Enterprise Vault API overviewLicensing

Enterprise Vault administration roles are described in the Enterprise Vault Administration guide.

LicensingNo 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 licensingThe 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 licensingThe STEP licensing contract does not grant production use of the Enterprise Vault APIs. Customer deployments of third-party applications and

Page 41: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

41Enterprise Vault API overviewDeploying an application that uses the API

customer-developed applications that make use of the Enterprise Vault APIs will require one of the following licenses, in addition to any third-party licensing requirements:

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

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

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

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

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

Enterprise Vault API runtime MSIThe 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.

Page 42: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

42 Enterprise Vault API overviewDeploying an application that uses the API

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

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

HKEY_LOCAL_MACHINE

\Software

\KVS

\Enterprise Vault

\API Runtime

\Install

On 64-bit versions of Windows Server, the Enterprise Vault registry settings are under the following location:

HKEY_LOCAL_MACHINE

\Software

\WOW6432node

\KVS

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

Checking version and installation path details prior to Enterprise Vault 8.0To 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.

Page 43: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

43Enterprise Vault API overviewDeploying an application that uses the API

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

■ HKEY_LOCAL_MACHINE

\Software

\KVS

\Enterprise Vault

\Install

\VaultServices

If the value of this setting is “Installed”, then Enterprise Vault server is installed.

■ HKEY_LOCAL_MACHINE

\Software

\KVS

\Enterprise Vault

\Install

\InstallPath

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

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

This requires an application configuration file with <dependentAssembly> entries for each of the Enterprise Vault API components used by the application.

The assembly redirections must include a <codebase> element that defines the location of the PIA and, optionally, a <bindingRedirect> element if the application is built against a different PIA version to the one deployed by the Enterprise Vault runtime.

See “Updating binding redirections in configuration files”.

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

tlbimp /nologo EVContentManagementAPI.dll

Page 44: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

44 Enterprise Vault API overviewInstalling the Enterprise Vault SDK

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

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

To update the application configuration file:

1 Open the client application’s configuration file, locate the Enterprise Vault <assemblyIdentity> nodes, and update any <bindingRedirect> and <codebase> nodes as illustrated in the following example to redirect any requests for an older version of an Enterprise Vault API Runtime file to the new version. For example:

<runtime>

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

<dependentAssembly>

<assemblyIdentity

name="KVS.EnterpriseVault.Interop.IndexClient"

culture="neutral" publicKeyToken="26c5e2ccf2b9267c"/>

<bindingRedirect oldVersion="7.5.4.2534"

newVersion="8.0.0.0"/>

<codeBase version="8.0.0.0" href=

"FILE:///C:\Program Files\Enterprise Vault\

KVS.EnterpriseVault.Interop.IndexClient.dll"/>

</dependentAssembly>

</assemblyBinding>

</runtime>

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

Installing the Enterprise Vault SDKThe 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

Page 45: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

45Enterprise Vault API overviewInstalling the Enterprise Vault SDK

Checking the SDK version and installation pathIf you are using Enterprise Vault 8.0 or later, you can query the registry settings InstallPath and Version in the following location to find out the the version of the Enterprise Vault API SDK installed and the installation path:

HKEY_LOCAL_MACHINE

\Software

\KVS

\Enterprise Vault

\Software Development Kit

\Install

On 64-bit versions of Windows Server, the Enterprise Vault registry settings are under the following location:

HKEY_LOCAL_MACHINE

\Software

\WOW6432node

\KVS

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

SDK examplesAn example application for the Content Management API is included in the Enterprise Vault SDK, in samples\ECM API Sample.

This example application has been built using Visual Studio 2005.

The application does not have a manifest configured. If the target Enterprise Vault server is running on Windows Server 2008, you may want to add an application manifest, as described in the MSDN article:http://msdn2.microsoft.com/En-US/library/bb756929.aspx

To build the test application

1 Install the SDK on your development server.

2 Open the project file TestECMClient.vcproj.

3 You need to tell the compiler where the Enterprise Vault binaries are located in your environment. In Visual Studio select Tools > Options > Projects and Solutions > VC++ directories. From the Show Directories for drop down list select Executable Files. Add the folder containing the Enterprise Vault binaries to the list of folders.

Page 46: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

46 Enterprise Vault API overviewProgramming notes

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

Programming notes■ As the API interfaces are derived from IDispatch, they can be used by

scripting languages.

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

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

Using the Enterprise Vault APIs in C++For each API, the associated DLL includes the type library for all of the classes, enumerations and interfaces of the API. When using Microsoft Visual Studio C++ to build an application using the API, the #import directive should be used to provide C++ definitions of the COM classes, interfaces and types.

For example, to use smart pointers, error wrapper functions and the EVContentManagementAPILib namespace:#import “EVContentManagementAPI.dll” using namespace EVContentManagementAPILib;

To exclude use of smart pointers, error wrapper functions and the EVContentManagementAPILib namespace:

#import “EVContentManagementAPI.dll” no_namespace, raw_interfaces_only

Using Enterprise Vault APIs .NET managed languagesWhen using .NET managed languages to build an application using an API, Interop assemblies provide the .NET definitions for the API COM type library. You can reference the SDK Primary Interop Assemblies (PIAs), the COM API library or Interop assemblies generated via tlbimp, depending upon the deployment model selected.

See “Deploying .NET applications” on page 43.

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

KVS.EnterpriseVault.Interop.EVContentManagementAPI.dll

Page 47: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

47Enterprise Vault API overviewProgramming notes

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

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

Using Enterprise Vault APIs in Visual Basic ScriptThe 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 samplesIn 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.

Page 48: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

48 Enterprise Vault API overviewProgramming notes

Page 49: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

4

Content Management API

This chapter provides the following information:

■ An overview of the Content Management API.

■ General guidelines for using the API.

■ Enumerations

■ Detailed reference information on each interface, method and property.

About the Content Management APIThe Content Management API comprises the following interfaces:

■ IContentManagementAPI

■ IContentManagementAPI2

■ IContentManagementAPI3

■ IContentManagementAPI4

■ IVaultStores

■ IVaultStore

■ IArchives

■ IArchive

■ IArchive2

■ IArchive3

■ IItems

■ IItem

■ IItem2

■ IItem3

Page 50: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

50 Content Management APIAbout the Content Management API

■ IContent

■ IArchiveMetaData

■ IArchiveMetaData2

■ ISimpleIndexMetadata

■ IComplianceData

■ IHolds

■ IHold

■ IExtendedErrorInfo

■ IDiagnosticsAPI

Table 3-1 on page 38 gives a brief summary of the operations that can be performed using the Content Management API.

The methods and properties exposed by all these interfaces are described in detail in this chapter.

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

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

Page 51: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

51Content Management APIAbout the Content Management API

Figure 4-1 Hierarchy of Content Management API objects

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

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

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

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

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

Page 52: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

52 Content Management APIGeneral guidelines for using the API

archived item first). The Items object exposes a standard COM collection interface that manages a collection of Item objects.

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

■ The Item object provides applications with a way to store and manage items in Enterprise Vault archives.

The following interfaces are implemented by the Item object:

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

■ IArchiveMetaData interface provides calling applications with a set of properties that describe how the item is archived. The following interfaces are exposed by IArchiveMetaData:

IComplianceData interface describes the compliance metadata set on an item in an archive.

ISimpleIndexMetaData interface enables the calling application to add custom index metadata to an object as it is archived. This can then be searched for using the Search API.

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

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

■ The ExtendedErrorInfo object provides calling applications with additional information on internal errors encountered when using Content Management API interfaces.

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

General guidelines for using the APITo use the Content Management API you need to obtain an instance of the ContentManagmentAPI object in the usual manner; by calling CoCreateInstance (C++), or by using the new operator (.NET managed code), for example.

See “Examples” on page 72.

You can then use the properties and methods on the interface to obtain instances of other objects.

Consider thread priority if normal Enterprise Vault Exchange Server journal or mailbox archiving is running in your environment in addition to a Content Management API application. If the API application archives large numbers of

Page 53: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

53Content Management APIGeneral guidelines for using the API

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

Use of objectsIt is best practice for the calling application to keep the ContentManagementAPI object alive as long as possible, as the ContentManagementAPI object caches information from Enterprise Vault, and frequent creation and release would result in poor performance of the client.

Most of the object instances obtained from the ContentManagementAPI object are designed to be used only once. This prevents reuse of stale data.

Once an object instance has been used (that is, Get, Insert or Create have been called), it can only be used for querying properties, not for setting them. Before any of these methods (Get, Insert or Create) can be called again, the existing object instance should be released and a new one obtained.

For example, the following steps are required when storing an item in an archive:

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

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

■ Call the Insert method.

■ Retrieve the item’s Id from the object property.

■ Release the Item object instance.

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

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

Enumerating vault stores, archives and itemsArchives 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

Page 54: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

54 Content Management APIGeneral guidelines for using the API

applications to enumerate and select vault stores and archives, and retrieve information about these from the Enterprise Vault Directory.

The IItems interface enables the application to enumerate the items in an archive, and retrieve information about these items from the Enterprise Vault Storage Service.

The IVaultStores, IArchives and IItems interfaces inherit the properties and methods of a generic collection enumeration interface, ICollectionBase. How to use this interface follows the general model for enumerating objects:

■ Obtain an empty collection instance from the ContentManagementAPI.

■ Populate the selection criteria properties.

■ Invoke the Get method to populate the collection.

■ Enumerate through the collection.

You can select archives using the following criteria:

■ By vault store; optionally filtered by archive type.

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

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

■ By archive type.

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

You select items using the following criteria:

■ By archive.

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

Saveset IDs and Transaction IDsAn 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

Page 55: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

55Content Management APIGeneral guidelines for using the API

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

Format of a Transaction ID valueA 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 validationThe syntax of a property is validated when the property is set, but validation of the value is typically delayed until the property is used, for example when invoking the Get method.

Adding custom index metadata Applications can add custom index metadata to an item as it is archived using the ISimpleIndexMetadata interface.

See “IArchiveMetaData :: IndexData” on page 253.

When the item is indexed, this custom metadata will be included in the index for the item. The Search API can then be used to search archives for items with the custom information.

See Figure 4-2 on page 56.

Custom filtering is available for both Exchange Server Archiving (for the Exchange Mailbox Archiving Task, Exchange Public Folder Task and Exchange Journaling Task) and Domino Server Archiving, and the following methods can be used to add custom index properties:

■ For Exchange Server filtering, the AddIndexedProperty and AddIndexedPropertyToSet methods of the IArchivingControl interface can be used.

See “IArchivingControl interface for Exchange filtering” on page 439.

■ For Domino Server filtering, the Add method in the IndexMetadata class can be used.

See “IArchivingControl interface” on page 483.

Page 56: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

56 Content Management APIGeneral guidelines for using the API

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

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

Audit loggingFrom Enterprise Vault 8.0, audit logging includes Content Management API item operations. Auditing for various categories of item operations from all Enterprise Vault agents can be enabled or disabled.

Table 4-1 lists the operations that can be logged and the associated Enterprise Vault audit category. Audit logging can be enabled for specific audit categories using the Enterprise Vault Administration Console.

Table 4-1 Operations logged and the associated audit category

API operation Enterprise Vault Audit Category

InsertCopyTo

Archive

MoveTo ArchiveDelete 1

Delete Delete

Page 57: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

57Content Management APIGeneral guidelines for using the API

Diagnostic logging and tracingThe 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.

Get View

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

Table 4-1 Operations logged and the associated audit category

API operation Enterprise Vault Audit Category

Page 58: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

58 Content Management APIEnumerations

EnumerationsThis section describes the enumerations used by the Content Management API.

EV_API_DELETION_LEVEL enumerationDeletion level enumeration defines the type of delete permitted for archived items:enum EV_API_DELETION_LEVEL{

DELETION_LEVEL_SOFT_DELETE = 0,DELETION_LEVEL_HARD_DELETE = 1

};

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

In the Enterprise Vault Administration Console, in the Site Properties pages, the administrator can enable the recovery of deleted items and specify how long soft-deleted items are to be kept.

This enumeration value is set using the Item DeletionLevel property.

See “IItem :: DeletionLevel” on page 190

EV_API_EVENT_TYPE enumerationEvent type enumeration indicates the type of event:enum EV_API_EVENT_TYPE{

EVENT_TYPE_ERROR = 1,EVENT_TYPE_WARNING = 2,EVENT_TYPE_INFORMATION = 3,EVENT_TYPE_SUCCESS_AUDIT = 4,EVENT_TYPE_FAILURE_AUDIT = 5

};

When an application creates a diagnostic message in the Enterprise Vault event log using the DiagnosticsAPI LogEvent method, this value indicates the type of message to create.

See “IDiagnosticsAPI : LogEvent” on page 367

EV_API_ITEMS_ORDERBY enumerationItems collection order defines whether to increase or decrease the index sequence number when enumerating a collection of items.

Page 59: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

59Content Management APIEnumerations

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 enumerationTrace level enumeration indicates the trace level:

enum EV_API_TRACE_LEVEL{

TRACE_LEVEL_HIGH = 1,TRACE_LEVEL_MEDIUM = 2,TRACE_LEVEL_LOW = 3

};

The method DiagnosticsAPI IsTraceEnabled tests if the specified level of tracing is enabled in the application for the Enterprise Vault tracing utility (Dtrace).

When sending a trace message to Dtace, the DiagnosticsAPI Trace method uses this enumeration to set the trace level to be associated with the message.

See “IDiagnosticsAPI : IsTraceEnabled” on page 366 and“IDiagnosticsAPI : Trace” on page 368

EV_STG_API_ARCHIVE_TYPE enumerationArchive type enumeration indicates the type of archive:enum EV_STG_API_ARCHIVE_TYPE{

ARCHIVE_TYPE_NOT_SET = 0x00000000,ARCHIVE_TYPE_SHARED = 0x00000001,ARCHIVE_TYPE_EXCHANGE_MAILBOX = 0x00000002,ARCHIVE_TYPE_EXCHANGE_JOURNAL = 0x00000004,ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER = 0x00000008,ARCHIVE_TYPE_FILE_SYSTEM = 0x00000010,ARCHIVE_TYPE_SHAREPOINT = 0x00000020,ARCHIVE_TYPE_DOMINO_JOURNAL = 0x00000040,ARCHIVE_TYPE_DOMINO_MAILBOX = 0x00000080

};

The properties, Archives ArchiveTypes and Archive Type, select archives based on the type of archive specified by this enumeration.

See “IArchives :: ArchiveTypes” on page 119 and “IArchive3 :: Type” on page 160

Page 60: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

60 Content Management APIEnumerations

EV_STG_API_AUTHENTICATE_USING enumerationStorage authentication enumeration indicates the authentication mode to use when authenticating to Enterprise Vault.enum EV_STG_API_AUTHENTICATE_USING{

AUTHENTICATE_USING_DCOM_SECURITY = 0,AUTHENTICATE_USING_AUTHSERVER = 1AUTHENTICATE_USING_MOST_APPROPRIATE_MODE = 2

};

AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default value. This value means that DCOM will be used.

Authentication using the Enterprise Vault authentication server can only be used by applications installed on a configured Enterprise Vault server, and should only be used on advice from Symantec Support.

See “IContentManagementAPI :: AuthenticationMode” on page 83

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

See “IItem :: CanBeDeleted” on page 206

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

Page 61: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

61Content Management APIEnumerations

EV_STG_API_CONVERTED_CONTENT enumerationWhen a file is archived, the Enterprise Vault Storage Service converts the file to HTML, if possible. The HTML version is used by the Indexing Service to index the item. The HTML version is also presented to users when the item is previewed or viewed using the Enterprise Vault Web Access application.

Store converted content enumeration indicates whether converted content is stored with the item, or generated on demand:enum EV_STG_API_CONVERTED_CONTENT{

CONVERTED_CONTENT_STORED = 0, CONVERTED_CONTENT_ON_DEMAND = 1

};

The property, Archive ConvertedContent, is used to set or retrieve the enumeration value.

See “IArchive :: ConvertedContent” on page 132

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

“IArchiveMetaData :: ComplianceData” on page 247

“IComplianceData :: SetBy” on page 312

SETBY_NOTSET A compliance retention period is not set.

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

SETBY_RETCAT The compliance retention period is set by the associated Enterprise Vault retention category.

Page 62: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

62 Content Management APIEnumerations

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

CP_UNITS_NONE is actually the default value, not CP_UNITS_DEFAULT.

See “IComplianceData :: Units” on page 308

EV_STG_API_DELETION_REASON enumerationDeletion 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 = 3DELETION_REASON_UNKNOWN = 2147483647

}

If an item no longer exists in the archive, the Item DeletionReason property can be used to find out why the item was deleted. the Item DeletionReason property uses the EV_STG_API_DELETION_REASON enumeration.

The enumeration values have the following meanings:

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

DELETION_REASON_USER Indicates that the item was deleted by a user.

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

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

Page 63: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

63Content Management APIEnumerations

See “IItem2 :: DeletionReason” on page 215

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

The property Archive ExpireItems can be used to return the enumeration value for an existing archive, or set the required value for a new archive before Archive Create is called.

See “IArchive :: ExpireItems” on page 130

EV_STG_API_INDEX_LEVEL enumerationIndex level enumeration indicates how much of an item is indexed:enum EV_STG_API_INDEX_LEVEL{

INDEX_LEVEL_BRIEF = 0,INDEX_LEVEL_MEDIUM = 1,INDEX_LEVEL_FULL = 2,INDEX_LEVEL_DEFAULT = 3

};

The Enterprise Vault Indexing service manages the indexes of archived data to enable users to search for archived items. When users search the archives to which they have access, the index volume files are searched. The more information that is indexed about an item, the quicker it is to find the item. However, the more information that is indexed about an item, the more disk space is required for the index.

For more information on indexing levels, see “Introduction to storing and indexing” on page 517.

FULL indexing is required for phrase searches of the content property (IndexPropCONT).

The property, Archive IndexLevel, is used to determine the level of detail stored in the archive’s index.

See “IArchive :: IndexLevel” on page 136

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

Page 64: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

64 Content Management APIEnumerations

EV_STG_API_INDEX_URGENCY enumerationIndex urgency enumeration indicates whether to index items as they are stored:enum EV_STG_API_INDEX_URGENCY{

INDEX_ITEMS_IMMEDIATELY = 0,INDEX_ITEMS_DEFER_INDEFINITELY = 1

};

Deferring indexing may be useful if you want to store a very large number of items quickly.

If INDEX_ITEMS_DEFER_INDEFINITELY is set, the items will not be indexed until the value has been reset to IMMEDIATELY. Thereafter, the next time the Indexing Service runs, it will process the indexing backlog.

The Archive IndexUrgency property is used to access index urgency information.

“IArchive :: IndexUrgency” on page 134

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

ITEM_COPYOPTIONS_UNSPECIFIED = 0x00000000, ITEM_COPYOPTIONS_ARCHIVEMETADATA = 0x00000002,ITEM_COPYOPTIONS_MERGE_INDEXMETADATA = 0x00000004

} ;

The default value is ITEM_COPYOPTIONS_ARCHIVEMETADATA.

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

SimpleIndexMetaData

ArchivedDate

RetentionCategory

CurrentLocation

CurrentFolder

CustomIdentifier

CustomQualifier

CustomProperties

Page 65: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

65Content Management APIEnumerations

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

See “IItem :: CopyOptions” on page 192

EV_STG_API_ITEM_DETAIL enumerationItem 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 = 128DETAIL_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.TitleIContent.AuthorIContent.FileExtensionIContent.MIMEFormatIContent.OriginalLocationIContent.CreatedDateIContent.ModifiedDateIContent.OriginalSizeIItem.CanBeDeletedIArchiveMetadata.IsItemSecured

See “Content object” on page 220

See “Item object” on page 172

See “ArchiveMetaData object” on page 237

DETAIL_LEVEL_ITEM_CONTENT IContent.Data

Page 66: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

66 Content Management APIEnumerations

For details of the Get method, see “IItem :: Get” on page 200.

For details of Enterprise Vault properties, see “System properties” on page 664.

EV_STG_API_PERMISSIONS_TYPE enumerationArchive permissions enumeration indicates archive permissions:enum EV_STG_API_PERMISSIONS_TYPE{

PERMISSIONS_UNSPECIFIED = 0x00000000,

DETAIL_LEVEL__ARCHIVE_METADATA IArchiveMetadata.ArchivedDateIArchiveMetadata.SavesetSizeIArchiveMetadata.RetentionCategoryIArchiveMetadata.CustomIdentifierIArchiveMetadata.CustomQualifierIArchiveMetadata.CustomPropertiesIArchiveMetadata.CurrentFolderIdIArchiveMetadata.SequenceNum

DETAIL_LEVEL__COMPLIANCE_DATA IArchiveMetadata.ComplianceDeviceIArchiveMetadata.RetentionExpires

DETAIL_LEVEL__HOLD_DATA IItem.Holds

See “Holds object” on page 313

DETAIL_LEVEL__CUSTOM_INDEX_METADATA IArchiveMetadata.IndexData — custom index properties only. (System properties are not included).

See “System properties” on page 664

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

See “System properties” on page 664

DETAIL_LEVEL__MESSAGE_ENVELOPE_INDEXDATA

IArchiveMetadata.IndexData — “menv” system property only.

See “System properties” on page 664

DETAIL_LEVEL__SENDER_RECIPIENT_INDEXDATA

IArchiveMetadata.IndexData — “sere” system property only.

See “System properties” on page 664

Table 4-2 Properties populated for EV_STG_API_ITEM_DETAIL enumeration values

Enumeration value Properties populated

Page 67: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

67Content Management APIEnumerations

PERMISSIONS_SEARCH = 0x00000080,PERMISSIONS_READ = 0x00000001,PERMISSIONS_WRITE = 0x00000002,PERMISSIONS_DELETE = 0x00000004,PERMISSIONS_FOLDER_READ = 0x00000008,PERMISSIONS_FOLDER_WRITE = 0x00000010,PERMISSIONS_FOLDER_DELETE = 0x00000020,PERMISSIONS_READ_WRITE = PERMISSIONS_READ|PERMISSIONS_WRITE,PERMISSIONS_READ_WRITE_DELETE= PERMISSIONS_READ

|PERMISSIONS_WRITE|PERMISSIONS_DELETE,

PERMISSIONS_WRITE_DELETE = PERMISSIONS_WRITE|PERMISSIONS_DELETE,

PERMISSIONS_READ_DELETE = PERMISSIONS_READ|PERMISSIONS_DELETE,

PERMISSIONS_FOLDER_READ_WRITE= PERMISSIONS_FOLDER_READ|PERMISSIONS_FOLDER_WRITE,

PERMISSIONS_FOLDER_READ_WRITE_DELETE = PERMISSIONSFOLDER__READ|PERMISSIONS_FOLDER_WRITE|PERMISSIONS_FOLDER_DELETE,

PERMISSIONS_FOLDER_WRITE_DELETE = PERMISSIONS_FOLDER__WRITE|PERMISSIONS_FOLDER_DELETE,

PERMISSIONS_FOLDER_READ_DELETE = PERMISSIONS_FOLDER_READ|PERMISSIONS_FOLDER_DELETE,

};

The Archives Permissions property uses this enumeration to select archives based on the archive access permissions of the caller.

The Archive SecurityDescriptor property represents the manually set permissions on an archive, which are displayed on the Permissions tab of the archive properties dialog in the Enterprise Vault Administration Console. EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security descriptor permissions for an archive.

See “IArchives :: Permissions” on page 117

See “IArchive3 :: SecurityDescriptor” on page 155

EV_STG_API_STATUS enumerationVault 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 = 2STS_INBACKUPMODE = 3

};

Page 68: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

68 Content Management APIEnumerations

The VaultStore Status and Archive Status properties use this enumeration to indicate the status of the vault store or archive, and whether it can be accessed.

“IVaultStore :: Status” on page 104

“IArchive2 :: Status” on page 151

Page 69: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

69Content Management APIContentManagementAPI object

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

Syntaxinterface IContentManagementAPI : IDispatchinterface IContentManagementAPI2 : IContentManagementAPIinterface IContentManagementAPI3 : IContentManagementAPI2interface IContentManagementAPI4 : IContentManagementAPI3

Member summary

Table 4-3 IContentManagementAPI properties

Property Read/Write Description

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

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

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

Page 70: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

70 Content Management APIContentManagementAPI 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.

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-3 IContentManagementAPI properties

Property Read/Write Description

Page 71: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

71Content Management APIContentManagementAPI object

RemarksThis interface returns pointers to instances of other interfaces, such as IVaultStores, IArchives, IItem, IHold, and IHolds. The properties of these need to be set so that they can then be used to create, fetch, move, enumerate and delete items, as required.

The interface also enables you to get and set the Directory DNS Alias and the authentication mode for accessing Enterprise Vault.

For best practice on using IContentManagementAPI, see “General guidelines for using the API” on page 52.

Requirements■ MSXML 3.0 or later is required on the computer where you install the

application using the API.

Version information■ The property, IContentManagementAPI::AuthenticationMode requires

Enterprise Vault 7.0 or later.

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.

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

Prog ID EnterpriseVault.ContentManagementAPI

Type Library EVContentManagementAPILib

DLL EVContentManagementAPI.dll

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

.NET PIA namespace KVS.EnterpriseVault.Interop

Page 72: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

72 Content Management APIContentManagementAPI object

■ The IContentManagementAPI2 interface requires Enterprise Vault 2007 or later.

■ The IContentManagementAPI3 interface requires Enterprise Vault 8.0 or later.

■ The IContentManagementAPI4 interface requires Enterprise Vault 8.0 SP2 or later.

Examples

C++

#import "c:\program files\Enterprise Vault\EVContentManagementAPI.dll" no_namespace, raw_interfaces_only

class SomeClass{ IContentManagementAPI4* m_pCmAPI = NULL;

public:

void SomeClass() { CLSID clsid; CLSIDFromProgID(L"EnterpriseVault.ContentManagmentAPI", &clsid);CoCreateInstance(clsid, NUKK, CLSCTX_ALL, __uuidof (IContentManagementAPI), reinterpret_cast<LPVOID*> (&m_pCmAPI));

//do something else}

C# using KVS.EnterpriseVault.Interop;

public class SomeClass{ IContentManagementAPI4 cmAPI = new ContentManagementClass();

//rest of class}

Page 73: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

73Content Management APIIContentManagementAPI :: Archive

IContentManagementAPI :: ArchiveThis 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.

SyntaxHRESULT Archive([out,retval] IArchive** pVal)

Parameters

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

Return value

ExamplesIn the following examples it is assumed a reference to IContentManagmentAPI, m_pCmAPI (C++) or cmAPI (C#) has already been obtained.

See “Examples” on page 72.

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

CComBSTR bstrID(L"1C9EFA88998592944ADB634ACC0D7410D1110000EVSite");

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 74: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

74 Content Management APIIContentManagementAPI :: Archive

CComBSTR bstrVaultStoreId(L"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite");

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;

Page 75: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

75Content Management APIIContentManagementAPI :: Item

IContentManagementAPI :: ItemThis 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.

SyntaxHRESULT Item([out, retval] IItem** pVal)

Parameters

RemarksAfter 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

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"1C9EFA88998592944ADB634ACC0D7410D1110000EVSite");

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 76: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

76 Content Management APIIContentManagementAPI :: Item

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

//get item propertiespItem->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 propertiesitm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);

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

See also■ IContent

■ IArchiveMetaData

■ ISimpleIndexMetaData

Page 77: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

77Content Management APIIContentManagementAPI :: Holds

IContentManagementAPI :: HoldsThis 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.

SyntaxHRESULT Holds([out, retval] IHolds** pVal)

Parameters

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

Return value

Examples

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

//Do something

pHolds->Release();

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 78: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

78 Content Management APIIContentManagementAPI :: Holds

pHolds = NULL;

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

See also■ IHold

Page 79: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

79Content Management APIIContentManagementAPI :: Hold

IContentManagementAPI :: HoldThis 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.

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

Parameters

RemarksThe 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

Examples

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 80: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

80 Content Management APIIContentManagementAPI :: Hold

//Set properties

pHolds->Add(pHold);

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

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

//add some properties

holds.Add(hold);

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

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

See also■ IHolds

Page 81: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

81Content Management APIIContentManagementAPI :: DirectoryDNSAlias

IContentManagementAPI :: DirectoryDNSAliasThis 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.

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

Parameters

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

HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID

The Id of an archive can be found in the Enterprise Vault Administration Console, in the properties dialog for an archive.

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

Return value

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

S_OK Success.

Page 82: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

82 Content Management APIIContentManagementAPI :: DirectoryDNSAlias

Examples

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

C# [out]

string dns = cmAPI.DirectoryDNSAlias;

[in]

cmAPI.DirectoryDNSAlias = dns;

Page 83: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

83Content Management APIIContentManagementAPI :: AuthenticationMode

IContentManagementAPI :: AuthenticationModeThis 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.

SyntaxHRESULT AuthenticationMode([out, retval]

EV_STG_API_AUTHENTICATE_USING* pVal)HRESULT AuthenticationMode([in]

EV_STG_API_AUTHENTICATE_USING newVal)

Parameters

RemarksEV_STG_API_AUTHENTICATE_USING enumerator defines the authentication mode to use.

See “EV_STG_API_AUTHENTICATE_USING enumeration” on page 60.

In releases prior to Enterprise Vault 7.0, authentication was performed using DCOM when the API application was not installed on an Enterprise Vault server, otherwise Enterprise Vault authentication server was used. From Enterprise Vault 7.0, DCOM authentication is used by default.

From Enterprise Vault 8.0 SP2, AUTHENTICATE_USING_MOST_APPROPRIATE_MODE is the default enumeration value. This value means that DCOM will be used.

Authentication using the Enterprise Vault authentication server can only be used by applications installed on a configured Enterprise Vault server, and should only be used on advice from Symantec Support.

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

Page 84: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

84 Content Management APIIContentManagementAPI :: AuthenticationMode

Return value

Examples

C++ m_pCmAPI->put_AuthenticationMode(AUTHENTICATE_USING_DCOM_SECURITY);

C# cmAPI.AuthenticationMode = EV_STG_API_AUTHENTICATE_USING.AUTHENTICATE_USING_DCOM_SECURITY;

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 85: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

85Content Management APIIContentManagementAPI2 :: VaultStores

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

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

Parameters

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

Return value

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Page 86: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

86 Content Management APIIContentManagementAPI2 :: VaultStores

See also■ “VaultStores object” on page 94.

Page 87: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

87Content Management APIIContentManagementAPI2 :: VaultStore

IContentManagementAPI2 :: VaultStoreThis 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.

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

Parameters

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

Return value

EXAMPLES

C++CComPtr<IVaultStore> spVaultStore;CComPtr<IUnknown> spUnk;m_pCmAPI->get_VaultStore(&pUnk);spUnk->QueryInterface(&spVaultStore);CComBSTR bstrID(L"16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite");spVaultStore->put_Id(bstrID);spVaultstore->Get();

C#IVaultStore vaultStore = cmAPI.VaultStore;

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Page 88: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

88 Content Management APIIContentManagementAPI2 :: VaultStore

vaultStore.ID = "16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite";vaultStore.Get();

See also■ “VaultStore object” on page 98.

Page 89: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

89Content Management APIIContentManagementAPI2 :: Archives

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

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

Parameters

Return value

EXAMPLES

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

See also■ “Archives object” on page 109.

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Page 90: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

90 Content Management APIIContentManagementAPI3 :: Items

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

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

Parameters

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

Return value

Example

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

// Get an Items object for enumerationspCMapi->get_Items(&spUnk);

CComQIPtr<IItems> spItems(spUnk);

See also■ “Items object” on page 162.

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Page 91: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

91Content Management APIIContentManagementAPI3 :: IDispatchQueryInterface

IContentManagementAPI3 :: IDispatchQueryInterface

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

■ IArchive3

■ IArchiveMetaData2

■ IItem2

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

SyntaxHRESULT IDispatchQueryInterface ([in] IDispatch* pUnkObj,

[in] BSTR interfaceId, [out, retval] IDispatch** ppUnkRetVal);

Parameters

RemarksThe pointer for returning the queried interface object returns NULL, and an error is reported, if the interface is not supported.

Return value

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

S_OK Success

Page 92: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

92 Content Management APIIContentManagementAPI3 :: IDispatchQueryInterface

ExampleThe 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, IAMD2set cmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")set item = ContentManagementAPI.Itemset IAMD2 = cmAPI.IDispatchQueryInterface(item.ArchiveMetaData, "{5C6882BD-24BE-4C32-87EF-C3701D949BAA}")if (IAMD2 is nothing) then MsgBox "ArchiveMetaData2 API Object create failed!"end if SeqNo = IAMD2.SequenceNum

See also■ “Archive object” on page 120

■ “ArchiveMetaData object” on page 237

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.

Page 93: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

93Content Management APIIContentManagementAPI4 :: LastError

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

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

Parameters

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

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

See “Programming notes” on page 46.

Return value

See also■ “ExtendedErrorInfo object” on page 355

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

S_OK Success

Page 94: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

94 Content Management APIVaultStores object

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

Syntaxinterface IVaultStores : ICollectionBase

Member summary

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

Table 4-8 IVaultstores properties

Property Read/Write Description

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

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.

Page 95: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

95Content Management APIVaultStores object

RemarksUse the ICollectionBase :: Get method of this interface to obtain a collection of VaultStore objects, and automatically populate the properties of each VaultStore object .

See “VaultStore object” on page 98.

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

Example

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

new ContentManagementAPI();IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores;// Populate collection from EV1vaultStores.Computer = “EV1.Acme.com”;vaultStores.Get();// Process each Vault Storeforeach(IVaultStore vaultStore in vaultStores){

ProcessIt(vaultStore.Id, vaultStore.Name);

}

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.

Page 96: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

96 Content Management APIIVaultStores :: Computer

IVaultStores :: ComputerThis property identifies an Enterprise Vault server running a Directory Service.

The property is read/write.

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

Parameters

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

■ DNS name

■ IP address

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

■ Enterprise Vault Site Id

■ Vault store Id

■ Archive Id

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

HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID

The Id of an archive can be found in the Enterprise Vault Administration Console, in the properties dialog for an archive.

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

If the Computer property is left empty than its value defaults to the current value of the DirectoryDNSAlias property of the parent IContentManagementAPI instance.

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

Page 97: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

97Content Management APIIVaultStores :: Computer

Return value

Example

C#IContentManagementAPI3 cmAPI = (IContentMangementAPI3)new ContentManagementAPI();IVaultStores vaultStores = (IVaultStores) CMAPI.VaultStores;// Populate collection from EV1vaultStores.Computer = “EV1.Acme.com”;vaultStores.Get();// Process each Vault Storeforeach(IVaultStore vaultStore in vaultStores){ProcessIt(vaultStore.Id, vaultStore.Name);}

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL

Page 98: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

98 Content Management APIVaultStore object

VaultStore objectThis object implements the following interface:

■ IVaultStore

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

Syntaxinterface IVaultStore : IDispatch

Member summary

RemarksIf you use the ICollectionBase interface to enumerate vault stores (see “VaultStores object” on page 94), then the IVaultStore properties are populated automatically for each vault store returned.

Alternatively, if you select a specific vault store using the Id property, you can call the Get method to populate the VaultStore properties.

Table 4-11 IVaultstore properties

Property Read/Write Description

Id Read/Write Vault store Id.

Name Read only Vault store name.

Description Read only Vault store description.

Status Read only Status of vault store.

ArchiveCount Read only Number of archives in the vault store.

DirectoryDNSAlias Read only Identifies an Enterprise Vault server running an Enterprise Vault Directory Service.

Table 4-12 IVaultStore methods

Method Description

Get Get the details of the selected vault store.

Page 99: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

99Content Management APIVaultStore object

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

Example

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

Page 100: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

100 Content Management APIIVaultStore :: Id

IVaultStore :: IdThis property contains the Id of the target vault store.

The property is read/write.

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

Parameters

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

Return value

Example

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

//now get vault store propertiesstring name = vaultStore.Name;string description = vaultsStore.Description;string dnsAlias = vaultStore.DirectoryDNSAlias;

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

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

S_OK Success.

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

Page 101: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

101Content Management APIIVaultStore :: Id

EV_STG_API_STATUS evStatus = vaultStore.Status;long count = vaultStore.ArchiveCount;

Page 102: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

102 Content Management APIIVaultStore :: Name

IVaultStore :: NameThis property contains the name of the selected vault store.

The property is read only.

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

Parameter

Return value

Example

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 103: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

103Content Management APIIVaultStore :: Description

IVaultStore :: DescriptionThis property contains the vault store description.

The property is read only.

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

Parameter

Return value

Example

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 104: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

104 Content Management APIIVaultStore :: Status

IVaultStore :: StatusThis property contains the status of the vault store.

The property is read only.

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

Parameter

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

Return value

Example

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

[out, retval] EV_STG_API_STATUS* pVal EV_STG_API_STATUS enumerated value.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 105: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

105Content Management APIIVaultStore :: ArchiveCount

IVaultStore :: ArchiveCountThis property contains the number of archives in the vault store.

The property is read only.

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

Parameter

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

Return value

Example

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

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

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.

Page 106: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

106 Content Management APIIVaultStore :: ArchiveCount

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

Page 107: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

107Content Management APIIVaultStore :: DirectoryDNSAlias

IVaultStore :: DirectoryDNSAliasThis property contains the DNS Alias created for the Enterprise Vault Site.

The property is read only.

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

Parameter

RemarksWhen 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

Example

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 108: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

108 Content Management APIIVaultStore :: Get

IVaultStore :: GetThis method returns the properties for the selected vault store.

SyntaxHRESULT Get(void);

RemarksIf 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

Example

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Id property is empty.

CONTENTMANAGEMENTAPI_E_NOT_FOUND The vault store does not exist.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory service is not running.

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

Page 109: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

109Content Management APIArchives object

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

Syntaxinterface IArchives : ICollectionBase

Member summary

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

Table 4-13 IArchives properties

Property Read/Write Description

Computer Read/Write An Enterprise Vault server running an Enterprise Vault Directory Service.

VaultStoreId Read/Write Id of the vault store containing the required archive or archives.

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

Permissions Read/Write Caller’s access permissions on the required archive or archives.

ArchiveTypes Read/Write Types of archives required.

Table 4-14 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.

Page 110: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

110 Content Management APIArchives object

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

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

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

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

Table 4-15 ICollectionBase methods

Method Description

Get Populate the collection.

Clear Clear the current collection.

Reset Reset the object back to the initial state.

Table 4-14 ICollectionBase properties

Property Read/Write Description

Page 111: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

111Content Management APIArchives object

No other combinations of properties are supported.

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

Example

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

See also■ “Enumerating vault stores, archives and items” on page 53.

■ “ICollectionBase : IDispatch” on page 344.

■ “Archive object” on page 120.

Page 112: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

112 Content Management APIIArchives :: Computer

IArchives :: ComputerThis property identifies an Enterprise Vault server running a Directory Service.

The property is read/write.

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

Parameters

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

■ DNS name

■ IP address

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

■ Enterprise Vault Site Id

■ Vault store Id

■ Archive Id

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

HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID

The Id of an archive can be found in the Enterprise Vault Administration Console, in the properties dialog for an archive.

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

If the Computer property is left empty than its value defaults to the current value of the DirectoryDNSAlias property of the parent IContentManagementAPI instance.

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

Page 113: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

113Content Management APIIArchives :: Computer

Return value

Example

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

archives.Permissions =EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;

archives.Get();

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 114: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

114 Content Management APIIArchives :: VaultStoreId

IArchives :: VaultStoreIdThis property contains the Id of the vault store that contains the required archive or archives.

The property is read/write.

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

Parameters

RemarksThe 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

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

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

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

S_OK Success.

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

Page 115: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

115Content Management APIIArchives :: ArchiveName

IArchives :: ArchiveNameThis property enables archives to be selected by name or partial name.

The property is read/write.

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

Parameters

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.

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

Page 116: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

116 Content Management APIIArchives :: ArchiveName

Return value

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

C#IArchives archs = cmAPI.Archives;archs.Computer = “SERVER1”;archs.ArchiveName = “*Smith”;archs.Get();

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL .

Page 117: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

117Content Management APIIArchives :: Permissions

IArchives :: PermissionsThis property enables selection of archives based on the archive access permissions of the caller.

The property is read/write.

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

Parameters

Remarks EV_STG_API_PERMISSIONS_TYPE is an enumerated type that indicates the required archive permissions. See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 66.

The permissions checks are based on the current Windows identity of the caller. If the caller is currently impersonating, then the impersonation identity is used.

Currently there is no support for the Lotus Domino authentication model.

Return value

Example

C#IArchives archives = (IArchives)cmAPI.Archives;archives.Computer = "EV1.acme.com";

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL .

Page 118: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

118 Content Management APIIArchives :: Permissions

archives.Permissions =EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;archives.Get();

Page 119: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

119Content Management APIIArchives :: ArchiveTypes

IArchives :: ArchiveTypesThis 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.

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

Parameters

Remarks EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive.

See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 59.

Return value

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL .

Page 120: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

120 Content Management APIArchive object

Archive objectThis object implements the following interfaces:

■ IArchiveIID is {48092C71-5618-4EB5-9060-01030C191450}

■ IArchive2IID is {B85C5178-0B9D-4987-8DC5-92F77B33879E}

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

Syntaxinterface IArchive : IDispatchinterface IArchive2 : IArchiveinterface IArchive3 : IArchive2

Member summary

Table 4-16 IArchive properties

Property Read/Write Description

VaultStoreId Read/Write Identifies the vault store in which the archive resides.

Id Read/Write Archive ID of the archive.

Name Read/Write Name of the archive.

Description Read/Write Provides description of the archive.

ExpireItems Read/Write Enables automatic storage expiry for archive.

ConvertedContent Read/Write Controls whether converted content is stored with item or generated on demand.

Page 121: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

121Content Management APIArchive object

IndexLevel Read/Write Sets level of indexing.

IndexUrgency Read/Write Control whether items are indexed on archiving.

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

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

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

ItemCount Read only Number of items in the archive.

Table 4-17 IArchive2 properties

Property Read/Write Description

Type Read only The type of the archive.

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

HasFolders Read only Whether archive structure is flat or has folders.

Full Read only Whether the archive is full.

DirectoryDNSAlias Read only Directory DNS Alias of the hosting the archive.

Table 4-18 IArchive3 properties

Property Read/Write Description

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

Table 4-16 IArchive properties

Property Read/Write Description

Page 122: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

122 Content Management APIArchive object

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

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

■ IArchive3 interface requires Enterprise Vault 8.0 or later.

Example

C#IArchive arch = cmAPI.Archive

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

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.

Table 4-18 IArchive3 properties

Property Read/Write Description

Page 123: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

123Content Management APIIArchive :: VaultStoreId

IArchive :: VaultStoreIdThis property identifies the vault store in which the archive resides or will reside.

The property is read/write.

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

Parameters

Return value

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

[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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Incorrect Id format.

Page 124: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

124 Content Management APIIArchive :: Id

IArchive :: IdThis property contains the Archive Id of the archive.

This property is read/write.

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

Parameters

RemarksThis 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

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

S_OK Success.

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

Page 125: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

125Content Management APIIArchive :: Id

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

or[out]

Assume an Archives object, 'archives', has been populated.foreach (IArchive archive in archives){

SearchArchive(archive.Id);}

Page 126: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

126 Content Management APIIArchive :: Name

IArchive :: NameThis property is used to set the name for a new archive or retrieve the name of an existing archive.

The property is read/write.

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

Parameters

RemarksThis property must be set before creating an archive, but is not required to get an archive.

Any attempt to change the name of an existing archive will result in an error.

The value must contain printable characters only, and cannot be blank or an empty string.

Return value

Example[in]arch.Name = “my new archive”;arch.Description = “my new archive description”;arch.ExpireItems = EV_STG_API_EXPIRE_ITEMS. DONT_EXPIRE_ITEMS;

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

S_OK Success.

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

Page 127: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

127Content Management APIIArchive :: Name

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

[out]arch.VaultStoreId = “16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;arch.Get();

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

Page 128: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

128 Content Management APIIArchive :: Description

IArchive :: DescriptionThis property contains a more complete description of the archive.

The property is read/write.

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

Parameters

RemarksThe [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

Examples

C++ CComBstr bstr = new CComBSTR(L”archive description”);archive->put_Description(bstr):

[in] BSTR newVal Description of the archive.

Max length: 127 characters.

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

S_OK Success.

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

Page 129: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

129Content Management APIIArchive :: Description

//do something – create archive//then check name

archive->get_ Description (&bstr);

//try changing namebstr = 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 namearchive. Description = “New description”; //ERROR

Page 130: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

130 Content Management APIIArchive :: ExpireItems

IArchive :: ExpireItemsThis property specifies whether or not items should be automatically deleted (expired) from the archive.

The property is read/write.

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

Parameters

RemarksThe required value must be set prior to calling Create.

The [in] property can only be used to set the ExpireItems value of a new archive before it is created. Any attempt to change this value in an existing archive will result in an error.

Do not attempt to retrieve a value for ExpireItems before creating or getting an archive, as an error will occur. No default value is set for this property.

EV_STG_API_EXPIRE_ITEMS is an enumeration type that indicates whether expired items should be deleted automatically from the archive.

See “EV_STG_API_EXPIRE_ITEMS enumeration” on page 63.

It may be necessary to cast this to an integer if using in C#.

Return value

[out, retval] EV_STG_API_EXPIRE_ITEMS* pVal Pointer to an EV_STG_API_EXPIRE_ITEMS object that will contain the currentvalue.

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

S_OK Success.

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

Page 131: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

131Content Management APIIArchive :: ExpireItems

Examples

C++ EV_STG_API_EXPIRE_ITEMS ei = DONT_EXPIRE_ITEMS;

archive->put_ExpireItems(ei);

//do other things and create archive//Now check value

archive->get_ExpireItems(&ei);

//try changing value

archive->put_ExpireItems(EXPIRE_ITEMS); //ERROR

C# EV_STG_API_EXPIRE_ITEMS ei =

EV_STG_API_EXPIRE_ITEMS.DONT_EXPIRE_ITEMS;

archive.ExpireItems = ei;

//do other things and create archive//Now check value

ei = archive.ExpireItems;

//try changing value

archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;

//ERROR

Page 132: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

132 Content Management APIIArchive :: ConvertedContent

IArchive :: ConvertedContentThis property specifies whether converted content is stored in the item or generated on demand.

The property is read/write.

SyntaxHRESULT ConvertedContent([out, retval]

EV_STG_API_CONVERTED_CONTENT* pVal);HRESULT ConvertedContent([in] EV_STG_API_CONVERTED_CONTENT newVal);

Parameters

RemarksThis property must be set before calling Create. Any attempt to retrieve the value of this property before Get or Create has been called will result in an error. Any attempt to change this value on an existing archive will result in an error.

EV_STG_API_CONVERTED_CONTENT enumeration indicates whether to store converted content with the item.

“EV_STG_API_CONVERTED_CONTENT enumeration” on page 61.

Return value

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

S_OK Success.

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

Page 133: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

133Content Management APIIArchive :: ConvertedContent

Examples

C++EV_STG_API_CONVERTED_CONTENT cc = CONVERTED_CONTENT_STORED;

archive->put_ConvertedContent(cc);

//do other things and create archive//Now check value

archive->get_ConvertedContent(&cc);

//try and change value

archive->put_ConvertedContent(CONVERTED_CONTENT_ON_DEMAND); //ERROR

C# EV_STG_API_CONVERTED_CONTENT cc = EV_STG_API_CONVERTED_CONTENT.CONVERTED_CONTENT_STORED;

archive.ConvertedContemt = cc;

//do other things – create archive//check value

cc = Archive.ConvertedContent;

//try and change the value

archive.ConvertedContent = EV_STG_API_CONVERTED_CONTENT.CONVERTED_ON_DEMAND; //ERROR

Page 134: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

134 Content Management APIIArchive :: IndexUrgency

IArchive :: IndexUrgencyThis property specifies when items are indexed.

The property is read/write.

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

Parameters

RemarksThis property must be set before calling Create. Any attempt to retrieve the value of this property before Get or Create have been called will result in failure.

EV_STG_API_INDEX_URGENCY enumeration indicates whether to index items as they are stored.

See “EV_STG_API_INDEX_URGENCY enumeration” on page 64.

Deferring indexing may be useful if you want to store a very large number of items quickly.

INDEX_ITEMS_DEFER_INDEFINITELY was originally introduced to be used with File System Archiving only. If this value is set, the items will not be indexed until the value has been reset to IMMEDIATELY, and the next time the Indexing Service runs it will process the index backlog.

Return value

[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

S_OK Success.

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

Page 135: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

135Content Management APIIArchive :: IndexUrgency

Examples

C++EV_STG_API_INDEX_URGENCYiu = 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

Page 136: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

136 Content Management APIIArchive :: IndexLevel

IArchive :: IndexLevelThis property determines the level of detail stored in the archive’s index.

The property is read/write.

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

Parameters

RemarksEV_STG_API_INDEX_LEVEL enumeration indicates how much of an item is indexed.

See “EV_STG_API_INDEX_LEVEL enumeration” on page 63.

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

When users search the archives to which they have access, the index volume files are searched. The more information that is indexed about an item, the quicker it is to find the item. However, the more information that is indexed about an item, the more disk space is required for the index.

Return value

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

S_OK Success.

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

Page 137: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

137Content Management APIIArchive :: IndexLevel

Examples

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

archive->put_IndexLevel(il);

//do something and create archive//Now check value

archive->get_ IndexLevel (&il);

//try and change value

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

C# EV_STG_API_INDEX_URGENCY il =

EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_MEDIUM;EV_STG_API_INDEX_URGENCY il =

EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_BRIEF;

archive. IndexLevel = il;

//do something – create archive//check value

il = Archive. IndexLevel;

//try and change the value

archive. IndexLevel = EV_STG_API_INDEX_LEVEL. INDEX_LEVEL_FULL;//ERROR

Page 138: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

138 Content Management APIIArchive :: Size

IArchive :: SizeThis property contains the size of the archive.

The property is read only.

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

Parameters

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

Return value

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

string name = arch.Name;

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

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.

Page 139: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

139Content Management APIIArchive :: Size

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

Page 140: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

140 Content Management APIIArchive :: SecurityDescriptor

IArchive :: SecurityDescriptorThis 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).

SyntaxHRESULT SecurityDescriptor([in] VARIANT newVal);

Parameters

RemarksAny attempt to modify the security descriptor of an existing archive will result in an error.

The self-relative security descriptor may override the current user.

If the type of the variant is VT_ARRAY then the variant is a byte array containing the SECURITY_DESCRIPTOR for the user account that will be given access to the archive.

If the type of the variant is VT_EMPTY then the security descriptor is set to default (that is, the user creating the archive has full access to the archive).

Finally a type of VT_NULL means that the archive is created without any permissions.

EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security descriptor permissions for an archive.

See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 66.

The values of the EV_STG_API_PERMISSIONS_TYPE enumerator may be combined (using OR) to set the required value. For example, to set search and read item, you would enter PERMISSIONS_SEARCH|PERMISSIONS_READ.

Version informationAt Enterprise Vault 8.0, this property is superceded by the IArchive3::SecurityDescriptor property.

See “IArchive3 :: SecurityDescriptor” on page 155.

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

Page 141: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

141Content Management APIIArchive :: SecurityDescriptor

Return value

Example

Creating a Security Descriptorchar aszPrompt[MAX_INPUT_BUFFER];wcout << L"Domain\\Account: " << flush;cin.getline(aszPrompt, MAX_INPUT); // Create Security Identifier from Domain and AccountCSid Sid;if (!Sid.LoadAccount(aszPrompt)){

return HRESULT_FROM_WIN32(GetLastError());}

// Create ACE (access-control entry)CDacl Dacl;if (!Dacl.AddAllowedAce(Sid, PERMISSIONS_READ_WRITE_DELETE)){

return HRESULT_FROM_WIN32(GetLastError());}

// Set information in a DACL (discretionary access-control list)CSecurityDesc SecurityDesc;SecurityDesc.SetDacl(Dacl);

// Convert security descriptor to self-relative formatSecurityDesc.MakeSelfRelative();

// Copy security descriptor to a byte arrayUINT SecurityDescLength = SecurityDesc.GetLength();const SECURITY_DESCRIPTOR *pSecurityDesc =

SecurityDesc.GetPSECURITY_DESCRIPTOR();CComSafeArray<BYTE> SecurityDescSafeArrayOfBytes;hr = SecurityDescSafeArrayOfBytes.Add(SecurityDescLength,

(BYTE*)pSecurityDesc);

VARTYPE vt = SecurityDescSafeArrayOfBytes.GetType();vt = vt | VT_ARRAY;SecurityDescriptor->vt = vt;SecurityDescriptor->parray = SecurityDescSafeArrayOfBytes.Detach();

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER newVal is invalid, or the object is already populated.

Page 142: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

142 Content Management APIIArchive :: ComplianceDevice

IArchive :: ComplianceDeviceThis property tells the caller whether the archive resides on a device capable of setting compliance periods.

The property is read only.

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

Parameters

RemarksIf 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

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

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which will contain the current 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.

Page 143: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

143Content Management APIIArchive :: ComplianceDevice

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

Page 144: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

144 Content Management APIIArchive :: ItemCount

IArchive :: ItemCountThis property tells the caller how many items are currently held in the archive.

The property is read only.

SyntaxHRESULT ItemCount([out,retval] VARIANT* pVal)

Parameters

RemarksThis 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

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

string name = arch.Name;

[out,retval] VARIANT* pVal Pointer to a VARIANT that will contain the current number of items in the archive.

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.

Page 145: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

145Content Management APIIArchive :: ItemCount

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

Page 146: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

146 Content Management APIIArchive :: Create

IArchive :: CreateThis method is used to create an archive.

SyntaxHRESULT Create(void)

RemarksTo create an archive the calling application must be in a role that includes the operation, ‘{DIR} Can manage Enterprise Vault Stores’. By default, the Enterprise Vault Storage Administrator and Power Administrator roles include this operation.

Before calling this method, the following properties must be set:

■ VaultStoreId

■ Name

■ IndexUrgency

■ ConvertedContent

■ ExpireItems

■ IndexLevel

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

■ CONVERTED_CONTENT_STORED and INDEX_ITEMS_DEFER_INDEFINITELY

■ CONVERTED_CONTENT_ON_DEMAND and INDEX_ITEM_IMMEDIATELY

If the archive is created successfully, the Id property will be populated with the archive Id from the Enterprise Vault Directory.

When an archive is created, it is always created as an Enterprise Vault shared archive.

See “IArchive3 :: Type” on page 160.

Return value

S_OK Success.

Page 147: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

147Content Management APIIArchive :: Create

Example

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

C#archive.Name = ”XYZRM_” + userName;archive.Description = “XYZ RM application archive”;archive.VaultStoreId = “181E669473B52E64384C9A7D9EACA0E7E1210000evsite”;archive.ExpireItems = EV_STG_API_EXPIRE_ITEMS.EXPIRE_ITEMS;archive.IndexLevel = EV_STG_API_INDEX_LEVEL.INDEX_LEVEL_FULL;

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

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

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

Page 148: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

148 Content Management APIIArchive :: Create

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

Page 149: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

149Content Management APIIArchive :: Get

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

SyntaxHRESULT Get(void)

RemarksThe 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

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

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.

Page 150: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

150 Content Management APIIArchive2 :: Type

IArchive2 :: TypeThis 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.

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

Parameters

RemarksEV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive.

See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 59.

Version informationAt Enterprise Vault 8.0, this property is superceded by the IArchive3::Type property.

See “IArchive3 :: Type” on page 160.

Return value

[out, retval] EV_STG_API_ARCHIVE_TYPE* pVal Pointer to an EV_STG_API_ARCHIVE_TYPE thatcontains the current value.

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 151: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

151Content Management APIIArchive2 :: Status

IArchive2 :: StatusThis property indicates the status of the archive, that is, whether it can be accessed.

The property is read only.

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

Parameters

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

Return value

ExampleIArchive2 arch2 = cmAPI.Archive2;

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

EV_STG_API_STATUS evStatus = arch2.Status;

if (evStatus == EV_STG_API_STATUS. STS_AVAILABLE){

//store some items

[out, retval] EV_STG_API_STATUS* pVal Pointer to an EV_STG_API_STATUS that contains the current value.

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 152: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

152 Content Management APIIArchive2 :: HasFolders

IArchive2 :: HasFoldersThis property indicates whether the archive is flat or contains a folder structure.

The property is read only.

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

Parameters

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

Return value

ExampleIArchive2 arch2 = cmAPI.Archive2;

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

bool hasFolders = arch2.HasFolders;

if (hasFolders == true){

//do something

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

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 153: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

153Content Management APIIArchive2 :: Full

IArchive2 :: FullThis property indicates whether the archive is full.

The property is read only.

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

Parameters

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

Return value

ExampleIArchive2 arch2 = cmAPI.Archive2;

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

bool full = arch2.Full;

if (!full){

//store some items

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

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 154: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

154 Content Management APIIArchive2 :: DirectoryDNSAlias

IArchive2 :: DirectoryDNSAliasThis property contains the DNS Alias created for the Enterprise Vault Site.

The property is read only.

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

Parameters

RemarksWhen 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

ExampleIArchive2 arch2 = cmAPI.Archive2;

arch.VaultStoreId = “16D002240AEDFAC45A44E7FBE88FDC7721210000EVSite”;arch.Id = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;string dnsAlias = arch2.DirectoryDNSAlias;

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

S_OK Success

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 155: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

155Content Management APIIArchive3 :: SecurityDescriptor

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

The property is read/write.

We recommend that you use the SecurityDescriptorString property to retrieve and set the security descriptor from applications.

See “IArchive3 :: SecurityDescriptorString” on page 157.

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

Parameters

RemarksIf the type of the variant is VT_ARRAY, then the variant is a byte array containing the SECURITY_DESCRIPTOR for the user account that will be given access to the archive.

If the type of the variant is VT_EMPTY then the security descriptor is set to default (that is, the user creating the archive has full access to the archive).

If the type of the variant is VT_NULL, then the archive is created without any permissions.

EV_STG_API_PERMISSIONS_TYPE enumeration indicates the security descriptor permissions for an archive. The values are logically OR'd to get the combined permissions.

See “EV_STG_API_PERMISSIONS_TYPE enumeration” on page 66.

Any attempt to modify the security descriptor of an existing archive will result in an error.

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

Page 156: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

156 Content Management APIIArchive3 :: SecurityDescriptor

Return value

Example

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

// Get an instance of an IArchive3 object to populate pCmAPI->get_Archive(&pArchive);

CComQIPtr<IArchive3> pArchive3(pArchive);

if (pArchive3 != NULL){

pArchive3->put_Id(CComBSTR(L"240A579483C52B89384A9D7D9EACA0E7E9350000evsite");

pArchive3->put_VaultStoreId(CComBSTR(L"181E669473B52E64384C9A7D9EACA0E7E1210000evsite"));

// Retrieve Archive information//pArchive3->Get();

// Fetch the SecurityDescriptor property value associated with archive//CComVariant varSecurityDescriptor;

pArchive3->get_SecurityDescriptor(&varSecurityDescriptor);

}

S_OK Success.

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

Page 157: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

157Content Management APIIArchive3 :: SecurityDescriptorString

IArchive3 :: SecurityDescriptorStringThis 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.

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

Parameters

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

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

Page 158: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

158 Content Management APIIArchive3 :: SecurityDescriptorString

Security Descriptor strings using C++The Microsoft SDK includes the functions ConvertStringSecurityDescriptorToSecurityDescriptor and ConvertSecurityDescriptorToStringSecurityDescriptor that can be used for converting a string format security descriptor into a valid SECURITY_DESCRIPTOR structure and vice-versa.

In addition, the ATL Library includes CSecurityDesc class with FromString method, which converts a string-format security descriptor into a valid, functional security descriptor, and a ToString method, which converts a security descriptor to a string format.

Security Descriptor strings using .NET managed codeString type and StringBuilder class are available for constructing the SecurityDescriptorString property values.

In addition, the ConvertStringSecurityDescriptorToSecurityDescriptor and ConvertSecurityDescriptorToStringSecurityDescriptor functions are available as described in “Security Descriptor strings using C++”.

Return value

Examples

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

This example shows the value associated with the Manual security descriptor setting for the archive to which the user has full permissions access.

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

S_OK Success.

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

Page 159: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

159Content Management APIIArchive3 :: SecurityDescriptorString

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

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

Page 160: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

160 Content Management APIIArchive3 :: Type

IArchive3 :: TypeThis 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.

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

Parameters

RemarksCurrently, newVal can only be set to ARCHIVE_TYPE_SHARED; any other value is treated as invalid.

Any attempt to change this value on an existing archive will result in an error.

EV_STG_API_ARCHIVE_TYPE enumeration indicates the type of archive.

See “EV_STG_API_ARCHIVE_TYPE enumeration” on page 59.

The value of the property IArchive::HasFolders will be implied from the Type property value. Table 4-20 shows the implied values. False means that the archive is flat. True means that the archive is structured.

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

Table 4-20 Structure of archive types

EV_STG_API_ARCHIVE_TYPE value HasFolders property value

ARCHIVE_TYPE_SHARED False

ARCHIVE_TYPE_EXCHANGE_MAILBOX True

ARCHIVE_TYPE_EXCHANGE_PUBLIC_FOLDER True

ARCHIVE_TYPE_EXCHANGE_JOURNAL False

ARCHIVE_TYPE_FILE_SYSTEM True

Page 161: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

161Content Management APIIArchive3 :: Type

Return value

Example[out]IArchive3 arch3 = cmAPI.Archive3;

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

EV_STG_API_ARCHIVE_TYPE evType = arch3.Type;

if (evType == EV_STG_API_ARCHIVE_TYPE. ARCHIVE_TYPE_EXCHANGE_MAILBOX){

// do something

[in]

IArchive3 arch3 = cmAPI.Archive3;

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

ARCHIVE_TYPE_SHAREPOINT True

ARCHIVE_TYPE_DOMINO_MAILBOX False

ARCHIVE_TYPE_DOMINO_JOURNAL False

Table 4-20 Structure of archive types

EV_STG_API_ARCHIVE_TYPE value HasFolders property value

S_OK Success.

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

Page 162: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

162 Content Management APIItems object

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

Syntaxinterface IItems : ICollectionBase

Member summary

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

Table 4-21 IItems properties

Property Read/Write Description

ArchiveId Read/Write The ID of the archive holding the items to enumerate.

StartSequenceNum Read/Write The starting item sequence number to be used when fetching a collection of item records.

OrderBy Read/Write The index sequence number ordering to be used when enumerating items in the collection.

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

Page 163: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

163Content Management APIItems object

RemarksCalling applications must have at least Read access to the target archive.

The following properties are populated for each Item object in the collection. If additional properties are required for an Item, the Get method should be called specifying the required detail level.

IItem::Id

IItem::ArchiveId

IArchiveMetaData2::SequenceNum

IArchiveMetaData2::CurrentLocation

IArchiveMetaData2::CurrentFolderId

IArchiveMetaData::RetentionCategory

IItem::CopyOptions

IItem::DeletionLevel

IArchvieMetaData::ComplianceDevice

IArchiveMetaData::OverrideOnholdRetCat

Populating these properties avoids the need to call Get to determine the source item information before calling CopyTo or MoveTo.

Note that the items collection will not include items that have been soft deleted from the archive, if this has been enabled. The soft delete functionality is enabled using the Enterprise Vault Administration Console; by selecting the archive setting, Enable recovery of user deleted items, in Site properties.

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.

Table 4-22 ICollectionBase properties

Property Read/Write Description

Page 164: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

164 Content Management APIItems object

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

Example

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

ULONGLONG LastSequenceNum;

// Get an Items object for enumerationspCMapi->get_Items(&spUnk);

CComQIPtr<IItems> spItems(spUnk);

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

do{

CComPtr<IItem> spItem;

// Fetch a batch of itemsspItems->Get();

// Process each item in collectionlong lCount = 0;spItems->get_Count(&lCount);

// Iterative loopfor(long idx = 0; idx < lCount; ++idx){

CComPtr<IUnknown> spUnk;

//Fetch item

Page 165: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

165Content Management APIItems object

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

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

// Remember the last item seq. no.CComPtr<IArchiveMetaData> spAMD;spItem->get_ArchiveMetaData(&spAMD);CComQIPtr<IArchiveMetaData2> spAMD2(spAMD);spAMD2->get_SequenceNum(&LastSequenceNum)

}

vbMore = spItems->More();

// Fetch next chunk of itemsif (vbMore){

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

}} while (vbMore)

See also■ “Enumerating vault stores, archives and items” on page 53.

■ “ICollectionBase : IDispatch” on page 344.

■ “Item object” on page 172.

■ “ArchiveMetaData object” on page 237.

■ “Content object” on page 220.

Page 166: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

166 Content Management APIIItems :: ArchiveId

IItems :: ArchiveIdThis property identifies the archive in which the required items are stored.

The property is read/write.

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

Parameters

RemarksNote that the value used can be either the Archive ID or the ID of a folder in the archive, as this identifies both the archive and the archive folder.

The Archive ID is displayed in the properties of the archive in the Administration Console.

The following gives an example value of the ArchiveId property:“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”

Return value

ExampleIContentManagementAPI4 cmAPI4 = new (IContentManagementAPI4)ContentManagementAPIClass();

IItems items = cmAPI4.Items;items.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;items.StartSequenceNum = 1000;

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

S_OK Success.

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

Page 167: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

167Content Management APIIItems :: ArchiveId

items.OrderBy = EV_API_ITEMS_ORDERBY.ITEMS_ORDERBY_ASC;

items.Get();

Page 168: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

168 Content Management APIIItems :: StartSequenceNum

IItems :: StartSequenceNumThis property specifies the Index Sequence Number (ISN) of the first item in the items collection.

The property is read/write.

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

Parameters

RemarksThe Index Sequence Number of an archived item is specified in the IArchiveMetaData2::SequenceNum property. This property can be used to determine the start Index Sequence Number for the collection enumeration.

See “IArchiveMetaData2 :: SequenceNum” on page 273.

Enterprise Vault item sequence numbers are not always consecutive, as items may have expired or been deleted.

The default value for this property is 1.

RequirementsWindows 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

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

S_OK Success.

Page 169: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

169Content Management APIIItems :: StartSequenceNum

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

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

Page 170: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

170 Content Management APIIItems :: OrderBy

IItems :: OrderByThis property is used to specify the index sequence number order to be used when enumerating items in the collection.

The property is read/write.

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

Parameters

RemarksThe default is to order by ascending index sequence number (ITEMS_ORDERBY_ASC).

See “EV_API_ITEMS_ORDERBY enumeration” on page 58.

Return value

ExampleIContentManagementAPI4 cmAPI4 = new (IContentManagementAPI3)ContentManagementAPIClass();

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL or newVal is invalid.

Page 171: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

171Content Management APIIItems :: OrderBy

items.Get();

Page 172: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

172 Content Management APIItem object

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

Syntaxinterface IItem : IDispatch

Member summary

Table 4-24 IItem properties

Property Read/Write Description

ArchiveId Read/Write Archive ID of the archive containing the required item.

Id Read/Write Identifier of the item in the archive.

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

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

BrowserViewURL Read only URL for viewing the archived item.

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

Page 173: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

173Content Management APIItem object

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.

Table 4-24 IItem properties

Property Read/Write Description

Page 174: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

174 Content Management APIItem object

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

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

Table 4-27 IItem3 method

Property Description

Undelete Recover an item that has been soft-deleted.

Page 175: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

175Content Management APIIItem :: ArchiveId

IItem :: ArchiveIdThis property identifies the archive in which the item is stored, or to be stored.

The property is read/write.

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

Parameters

RemarksNote 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

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

Maximum length of string: 127 characters.

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

S_OK Success.

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

Page 176: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

176 Content Management APIIItem :: ArchiveId

Examples

C#IItem itm = cmAPI.Item;itm.ArchiveId = "“181E669473B52E64384C9A7D9EACA0E7E1110000evsite";itm.Id = "161000000000000~200501051649270000~0~9039eb282e3d4083b7

9f3298dc8a1e60";itm.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);

Page 177: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

177Content Management APIIItem :: Id

IItem :: IdThis property identifies the item in the archive.

This property is read/write.

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

Parameters

RemarksThis property sets or retrieves the identifier of the item in the archive. It is only populated once an item has been stored in an archive, and must be set before calling the Get method.

It should not be set before calling an Insert method, as this will result in an error.

Any attempt to change the value of an existing item will result in an error.

This property can hold the item’s Transaction ID or Saveset ID.

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

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

Return value

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

S_OK Success.

S_FALSE Success. The default value (NULL) is returned.

Page 178: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

178 Content Management APIIItem :: Id

Examples

C++ CComBSTR bstr(L“161000000000000~200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60“)

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

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.

Page 179: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

179Content Management APIIItem :: Content

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

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

Parameters

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

■ Title

■ OriginalLocation

■ FileExtension

■ MimeFormat

■ CreatedDate

■ ModifiedDate

■ Data

■ OriginalSize

■ Author

See “Content object” on page 220.

Return value

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

S_OK Success.

Page 180: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

180 Content Management APIIItem :: Content

Examples

C++ IContent* pContent = NULL;

item->get_Content(&pContent);

C# item.Get((int)EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES);IContent content= item.Content;LogContentProperties(content, item.Id);

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 181: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

181Content Management APIIItem :: ArchiveMetaData

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

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

Parameters

RemarksThe IArchiveMetaData interface makes available properties that hold information about the item, such as the assigned Retention Category and the date and time when the item was archived. Each of these is described in more detail in the relevant section.

See “ArchiveMetaData object” on page 237.

Return value

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pVal is NULL.

Page 182: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

182 Content Management APIIItem :: ArchiveMetaData

See also■ See “ArchiveMetaData object” on page 237.

Page 183: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

183Content Management APIIItem :: BrowserViewURL

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

SyntaxHRESULT BrowserViewURL([out,retval] BSTR* pVal)

Parameters

RemarksThis property will return an error if the archive Id and item Id have not been set previously.

The URL returned includes the IIS virtual directory for the Enterprise Vault Web access application, but not a specific Web server name. Enterprise Vault dynamically generates the full URL as needed, with the appropriate server name for each caller.

This form of URL is compatible with Enterprise Vault Building Blocks architec-ture.

Return value

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

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.

Page 184: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

184 Content Management APIIItem :: BrowserViewURL

Examples

C++ CComBSTR bstr;

item->put_Id(L”161000000000000~200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60“); item->put_ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite“);

item->get_BrowserViewURL(&bstr);

C# item.Id = ”161000000000000~200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60“;

Item.arhiveId = “181E669473B52E64384C9A7D9EACA0E7E1110000evsite“;

String url = Item.BrowserViewURL;

Page 185: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

185Content Management APIIItem :: DefaultMSGFormat

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

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

Parameters

RemarksThe following values can be assigned to newVal:

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

[in] BSTR newVal New value to be set.

See “Remarks”.

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

“N” Perform no conversion.

"U" Return as Unicode.

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

Page 186: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

186 Content Management APIIItem :: DefaultMSGFormat

earlier release than Enterprise Vault 6.0 SP1, this means that items archived prior to Enterprise Vault 6.0 SP1 are returned in ANSI format, and items archived since the upgrade to Enterprise Vault 6.0 SP1 are returned in Unicode format.

If a value has not been explicitly set, then this property will return null.

Return value

Examples

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

//do something, put ids etcItem->Get(DETAIL_LEVEL_ALL);Itm->put_DefaultMSGFormat(L”N”); // ERROR

C# itm.DefaultMSGFomart = “U”;

//do something – set ids etcItm.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ALL));Itm.=defaultMSGFormat = “N”; //ERROR

S_OK Success.

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

Page 187: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

187Content Management APIIItem :: Holds

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

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

Parameters

RemarksThis property is a collection of IHold pointers, each of which defines a hold placed on the particular item.

The caller must have called the IItem.Get method with the DETAIL_LEVEL_HOLD_DATA flag set prior to calling this property.

See “IItem :: Get” on page 200.

This property is a collection of IHold pointers, each of which defines a hold placed on the particular item.

Return value

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

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

S_OK Success.

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

Page 188: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

188 Content Management APIIItem :: NativeItemURL

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

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

Parameters

Remarks There will be an error if either the item Id or the archive Id have not been set before using this property.

The URL returned includes the IIS virtual directory for the Enterprise Vault Web access application, but not a specific Web server name. Enterprise Vault dynamically generates the full URL as needed, with the appropriate server name for each caller.

This form of URL is compatible with Enterprise Vault Building Blocks architec-ture.

Return Value

Examples

C++ CComBSTR bstr;

item->get_NativeItemURL(&bstr); //ERROR

[out, retval] BSTR* pVal A pointer to a BSTR that will contain the current 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.

Page 189: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

189Content Management APIIItem :: NativeItemURL

item->put_Id(L”200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”) item->put_ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”); item->get_NativeItemURL(&bstr); //SUCCESS

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

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

item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);string url = item.NativeItemURL; //SUCCESS

Page 190: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

190 Content Management APIIItem :: DeletionLevel

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

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

Parameters

RemarksEV_API_DELETION_LEVEL is an enumerated value.

See “EV_API_DELETION_LEVEL enumeration” on page 58.

The default value for this property is DELETION_LEVEL_SOFT_DELETE. For a period of time after deletion (configured by the administrator), users can recover a soft-deleted item.

In the Enterprise Vault Administration Console, in the Site Properties pages, the administrator can enable the recovery of deleted items and specify how long soft-deleted items are to be kept.

The Item Undelete method can be used to recover a soft-deleted item.

See “IItem3 :: Undelete” on page 217

Version information■ The ability to retrieve deleted items in Enterprise Vault is available from

Enterprise Vault 2007.

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

Page 191: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

191Content Management APIIItem :: DeletionLevel

Return Value

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;

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,or newVal is invalid.

Page 192: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

192 Content Management APIIItem :: CopyOptions

IItem :: CopyOptionsThis property identifies the source item property values to be copied to the destination item.

The property is read/write.

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

Parameters

RemarksThe calling application sets the CopyOptions property on the destination item object that is supplied in calls to the CopyTo or MoveTo methods.

The value of CopyOptions can be one or more of the EV_STG_API_ITEM_COPYOPTIONS enumeration values. The default value is ITEM_COPYOPTIONS_ARCHIVEMETADATA. If this is set, then the values of the following ArchiveMetaData properties on the source item will be copied to the equivalent properties on the destination item, unless explicitly provided as part of the CopyTo or MoveTo method call:

■ SimpleIndexMetaData

■ ArchivedDate

■ RetentionCategory

■ CurrentLocation

■ CurrentFolder

[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 themwith ‘OR'.

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

Page 193: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

193Content Management APIIItem :: CopyOptions

■ CustomIdentifier

■ CustomQualifier

■ CustomProperties

See “EV_STG_API_ITEM_COPYOPTIONS enumeration” on page 64.

Specifying item property override valuesBefore 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 on destination item

Property value in 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.

No No Set to current date/time.

RetentionCategory Yes (Default) Yes Set to override value.Set to the site default Retention Category if override value specified as a zero length string value.

No Yes As above.

Page 194: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

194 Content Management APIIItem :: CopyOptions

Return value

Yes (Default) No Copied from source item. 1

No No Set to the site default Retention Category.

CustomIdentifierCustomQualifierCustomProperties

Yes (Default) Yes Set to override value. 2

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.

CurrentLocationCurrentFolderId

Yes (Default) Yes Set to override value.

No Yes See “Which properties determine the current archive folder” on page 267.

Yes (Default) No Copied from source item. 3

No No See “Which properties determine the current archive folder” on page 267.

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

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

Item property Option selected

Override value set on destination item

Property value in copied item

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.

Page 195: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

195Content Management APIIItem :: CopyOptions

Examples

Visual Basic Script exampleIn the following example the source item’s ArchiveMetaData values are preserved on the destination item.Dim ecmAPISet ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")

Dim oItem, oDestItem

' Establish the source item

Set oItem = ecmAPI.Item

' Establish the destination item

Set oDestItem = ecmAPI.Item

oDestItem.ArchiveId = “181E669473B52E64384C9A7D9EACA0E7E1110000evsite”

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

oDestItem.CopyOptions = 3

oItem.CopyTo (oDestItem)

Page 196: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

196 Content Management APIIItem :: Insert

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

SyntaxHRESULT Insert(void);

RemarksIt is important to make sure that this interface pointer has not been used before to perform an Insert or Get action.

The caller must have WRITE access permissions on the destination archive, otherwise an error will occur. For structured archives, the caller must have write access to the destination archive folder.

If an override value is specified for the ArchivedDate property, the calling application must be in an Enterprise Vault role that includes the operation, “{API} Can Use Extended API Features”. This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles.

The Insert method stores an item in the specified archive. Before calling Insert, the following properties must be populated:

■ IItem :: ArchiveId

■ IContent :: Data

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

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

After this method has been called, and assuming the operation was successful, the Id property will be populated with the identifier of the item in the archive.

Calling this method on an Item that already contains an Id (that is, an item that has already been stored) will cause an error condition.

Content type File extension MIME format

Outlook messages .msg application/vnd.ms-outlook

SMTP messages .eml message/rfc822

Page 197: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

197Content Management APIIItem :: Insert

Return value

S_OK Success.

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

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

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

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The target archive is full or exceeds its quota limit.

Page 198: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

198 Content Management APIIItem :: Insert

Examples

C+ + spItem.put->ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”); IContent* pContent = null; spItem->get_Content(&pContent);

pContent->put_Title(L"new title");pContent->put_FileExtension(L"msg");

pContent->put_Data(L“C:\\temp\\test.msg”); spItem->Insert();

C# item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);

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

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

CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID Item Id is not unique in the target vault store.

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

Page 199: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

199Content Management APIIItem :: Insert

See Also“Content object” on page 220

Page 200: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

200 Content Management APIIItem :: Get

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

SyntaxHRESULT Get([in] LONG DetailLevel);

Parameters

RemarksThe item's ArchiveId and either its Id property or IArchiveMetaData::CustomIdentifier and IArchiveMetaData::CustomQualifier properties must be set prior to calling this method.

When retrieving hold data only, the item's Id property must be used (DetailLevel = DETAIL_LEVEL_HOLD_DATA).

The item's CustomIdentifier and CustomQualifier properties can only be used when together they uniquely identify an item.

See “IIArchiveMetaData :: CustomIdentifier” on page 257.

EV_STG_API_ITEM_DETAIL indicates the data to retrieve for an item.

See “EV_STG_API_ITEM_DETAIL enumeration” on page 65.

The caller can “bitwise OR” the bit masks together. For example, IItem.Get(255) returns the item properties and the metadata.

If the soft delete feature has been enabled, items that have been soft deleted from the archive are retrieved. The soft delete functionality is enabled using the Enterprise Vault Administration Console; by selecting the archive setting, Enable recovery of user deleted items, in Site properties.

To retrieve the item content, the caller must populate the IContent::Data property with a file location on disk, or to an IStream or ILockbytes object that has been created ready to receive the item content.

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

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

See “EV_STG_API_ITEM_DETAIL enumeration” on page 65.

Page 201: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

201Content Management APIIItem :: Get

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

See “IContent :: Data” on page 232.

When DETAIL_LEVEL__SYSTEM_INDEXDATA is requested, the “cont” property is included in the properties returned. This is the HTML representation (converted content) of the item or attachment. If the size of the item’s converted content is larger than 5MB, then the converted content is not returned. Instead, a content missing reason (“comr”) property is returned with the reason, vmrVALUENOTOBTAINED (2).

This limit can be changed using the registry setting: HKEY_LOCAL_MACHINE\Software\KVS\Enterprise Vault\MaxIndexDataHTMLContentKB

This registry setting is described in the Registry Values guide.

Return values

S_OK Success.

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directoryor 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.

Page 202: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

202 Content Management APIIItem :: 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 33.

Note that this feature requires MSXML 3.0 or later.

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

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

ExamplesRefer to Microsoft documentation for details and usage of IStorage and IStream.

C++ item->put_Id(

L” 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”);item->put_ArchiveId(L“181E669473B52E64384C9A7D9EACA0E7E1110000site“);IStorage* pStorage = NULL;StgCreateStorageEx(NULL, STGM_READWRITE | STGM_CREATE, STGFMT_FILE,

0, NULL, 0, NULL, IID_IStorage,reinterpret_cast<void**>(&pStorage));

IStream* pStream = NULL;

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 CustomIdentifierand CustomQualifier properties.

Page 203: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

203Content Management APIIItem :: Get

pStorage->CreateStream(„Test Stream“, STGM_READSWRITE |STGM_CREATE, 0, 0, &pStream);

IContent* pContent = NULL;item->get_Content(&pContent);

pContent->put_Data(pStream);

item->Get(DETAIL_LEVEL_ITEM_CONTENT);

//do something

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

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

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

item.Get((int)(EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_CONTENT));//do something

Page 204: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

204 Content Management APIIItem :: Delete

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

SyntaxHRESULT Delete(void);

RemarksCalling the Delete method will remove the item from its archive. The value of the DeletionLevel property will determine whether a hard or soft delete is performed.

Prior to calling this method, the application programmer must have set the ArchiveId (to identify the archive containing the item), and the Id property to identify the item within its container.

It cannot be called on an item whose ArchiveId and Id properties have not been set, as this will cause an error.

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

Return value

S_OK Success.

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

CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id is unknown or has been deleted.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

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

Page 205: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

205Content Management APIIItem :: Delete

Examples

C++ item->put_Archive_Id(L”181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);item->putId(L“181E669473B52E64384C9A7D9EACA0E7E1110000evsite“);

item->Delete();

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

object obj = item.CanBeDeleted;int canBeDeleted = (int)obj;if (obj == 0){

item.Delete();}

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.

Page 206: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

206 Content Management APIIItem :: CanBeDeleted

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

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

Parameters

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

Return value

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

S_OK Success.

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

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

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

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

Page 207: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

207Content Management APIIItem :: CanBeDeleted

ExampleIItem 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();}

Page 208: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

208 Content Management APIIItem :: CopyTo

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

SyntaxHRESULT CopyTo([in] IItem* DestinationItem);

Parameters

RemarksThe source and destination archive and vault store may be different, but the source and destination site must be the same.

The caller must have READ access to the source archive, and WRITE access permissions on the destination archive, otherwise an error will occur. For structured archives, the caller must have READ access to the source archive folder and WRITE access to the destination archive folder.

If an override value is specified for the ArchivedDate property, the calling application must be in an Enterprise Vault role that includes the operation, “{API} Can Use Extended API Features”. This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles.

When copying an item:

■ Create the destination item object.

■ Set the ArchiveId on the destination item object.

■ Set CopyOptions properties on the destination item object.

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

The CopyOptions property on the destination item object specifies the item elements to be copied across to the destination item.

See “IItem :: CopyOptions” on page 192.

From Enterprise Vault 8.0, the default action has changed; the item content and its associated ArchiveMetaData and IndexData elements are copied from the source item. This means that the default behaviour preserves the original ArchivedDate and OriginalLocation on the destination item, if override values are not specified.

[in] IItem* DestinationItem IItem interface pointer that represents the destination item.

Page 209: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

209Content Management APIIItem :: CopyTo

For backwards compatibility, the calling application can set suitable override values on the destination item object.

See “Specifying item property override values” on page 193.

For important considerations when specifying the destination archive folder, see “Which properties determine the current archive folder” on page 267.

Return value

S_OK Success.

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

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

Page 210: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

210 Content Management APIIItem :: CopyTo

Examples

C++ IItem* pItemSrc = NULL;pCmAPI->get_Item(&pItemSrc);pItemSrc->put_ArchiveId(CComBSTR(L”181E669473B52E64384C9A7D9EACA0E7E1110000evsite”));pItemSrc->put_Id(CComBSTR(L“334880000000000~200707251102240000~0~D3962A35951E4B03AE9CFB68AFE1218“));

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

IArchiveMetaData* pDstAMD = NULL;

CONTENTMANAGEMENTAPI_E_NOT_FOUND The source or destination Archive Id is unknown or has been deleted, or the selected retention category is not known or has been deleted or the source item cannot be found or has been deleted.

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is full or exceeds its quota limit.

CONTENTMANAGEMENTAPI_E_NO_ACCESS No access to the archive or archive folder, oror 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).

Page 211: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

211Content Management APIIItem :: CopyTo

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

IComplianceData* pDstComp = NULL;pDstAMD->get_ComplianceData(&pDstComp);pDstComp->SetBy(SETBY_RETCAT);

pItemSrc->CopyTo(pItemDst);

C# IItem itemSrc = cmAPI.Item;IItem itemDst = cmAPI.Item;itemSrc.ArchiveId =“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”;itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03AE9CFB68AFE1218”;

itemDst.ArchiveMetaData.RetentionCategory = “Business”;itemDst.ArchiveMetaData.ComplianceData.SetBy =

EV_STG_API_CP_SETBY.SETBY_RETCAT;itemSrc.CopyTo(itemDst);

Page 212: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

212 Content Management APIIItem :: MoveTo

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

SyntaxHRESULT MoveTo([in] IItem* DestinationItem);

Parameters

RemarksThe source and destination archive and vault store may be different, but the source and destination site must be the same.

The caller must have DELETE access to the source archive and archive folder, and WRITE access permissions on the destination archive and archive folder, otherwise an error will occur.

If an override value is specified for the ArchivedDate property, the calling application must be in an Enterprise Vault role that includes the operation, “{API} Can Use Extended API Features”. This operation is included in the default Enterprise Vault Power Administrator and Storage Administrator roles.

The MoveTo method is identical to the CopyTo operation, but it additionally removes the source item from the source archive after the copy has completed.

See “IItem :: CopyTo” on page 208.

The CopyOptions property on the destination item object specifies the item elements to be copied across to the destination item.

See “IItem :: CopyOptions” on page 192.

Return value

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

S_OK Success.

Page 213: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

213Content Management APIIItem :: MoveTo

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

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

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

CONTENTMANAGEMENTAPI_E_NOT_FOUND The source or destination Archive Id is unknown or has been deleted, or the selected retention category is not known or has been deleted or the source item is not found or has been deleted.

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL The destination archive is full or exceeds its quota limit.

Page 214: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

214 Content Management APIIItem :: MoveTo

ExampleIItem itemSrc = cmAPI.Item;IItem itemDst = cmAPI.Item;itemSrc.ArchiveId =“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”;itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03AE9CFB68AFE1218”;itemDst.ArchiveMetaData.RetentionCategory = “Business”;itemDst.ArchiveMetaData.ComplianceData.SetBy =EV_STG_API_CP_SETBY.SETBY_RETCAT;itemSrc.MoveTo(itemDst);

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

CONTENTMANAGEMENTAPI_E_NO_ACCESS The caller does not have delete access to the source archive or archive folder, or does not have write access to the destination archive or archive folder,oror 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).

Page 215: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

215Content Management APIIItem2 :: DeletionReason

IItem2 :: DeletionReasonIf 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.

SyntaxHRESULT DeletionReason([out,retval]

EV_STG_API_DELETION_REASON* pVal)

Parameters

RemarksIf an attempt to retrieve an item fails because the item cannot be found, then the DeletionReason property can be used to determine if the item has been deleted.

The property is populated only when it is accessed.

To retrieve the DeletionReason property, Item::Id and Item::ArchiveId properties must be specified on the Item object.

EV_STG_API_DELETION_REASON is an enumeration value that identifies why the item was deleted.

See “EV_STG_API_DELETION_REASON enumeration” on page 62

Return value

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

S_OK Success.

S_FALSE Success. The default value (NULL) is returned.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is NULL, or the item's Archive Id or Id property have not been set.

CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have read access to the archive.

Page 216: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

216 Content Management APIIItem2 :: DeletionReason

Examples

C#Item2 destItem = (IItem2)cmAPI.Item;destItem.ArchiveId = ="1BFE65542AFD18F418824B15EF3288CD51110000

EVServer.corp.com";destItem.Id = "200908040000000~200908041247260000~Z~80BD742AD7B88D0

850524974B9F44901";try{

// Try to get the itemdestItem.Get((int)(

EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ITEM_PROPERTIES|EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_ARCHIVE_METADATA|EV_STG_API_ITEM_DETAIL.DETAIL_LEVEL_SYSTEM_INDEXDATA));

}catch (COMException e){

// If ITEM NOT FOUND error is thrown, // check the deletion reason of the item.if (e.ErrorCode == (int)EV_STG_API_ErrorCodes.

CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND){

EV_STG_API_DELETION_REASON delReason =EV_STG_API_DELETION_REASON.DELETION_REASON_UNKNOWN;

try{

delReason = destItem.DeletionReason;}finally{

// Log that the item was not found together with the// deletion reasonLogItemNotFound(destItem, delReason);

}}

}

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.

Page 217: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

217Content Management APIIItem3 :: Undelete

IItem3 :: UndeleteIf 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.

SyntaxHRESULT Undelete([out, retval] VARIANT_BOOL* pVal)

Parameters

RemarksThe 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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_NOT_FOUND The target Archive Id has not been found.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pointer (pVal) passed in is NULL, or the item's Archive Id or Item Id property have not been set.

CONTENTMANAGEMENTAPI_E_NO_ACCESS Caller does not have undelete access to the archive. That is, the caller is not in a role that allows the operation, “Can undelete items in any archive”.

Page 218: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

218 Content Management APIIItem3 :: Undelete

Version information■ IItem3 interface requires Enterprise Vault 9.0.

See also■ “IItem :: DeletionLevel” on page 190

Examples

C#IItem3 item = (IItem3)cmAPI.Item;

item.ArchiveId = “118F819534E391C43B6854E2DD3A708C61110000EV.example.com”;item.Id = “201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51651”;

bool UnDeleted = item.Undelete();

Visual Basic ScriptDim ecmAPI, oItem, oItem3

Set ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")set oItem = ecmAPI.Item

set oItem3 = ecmAPI.IDispatchQueryInterface(oItem,"{E5C7F710-36AD-4e24-B00A-E3D709FF76CD}")

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.

Page 219: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

219Content Management APIIItem3 :: Undelete

oItem3.ArchiveId = "118F819534E391C43B6854E2DD3A708C61110000EV.example.com"oItem3.ID = "201004211843143~201004210854360000~Z~60B6FB033CED482A90683BFE5EA51651"

dim resultsresult = oItem3.Undelete

if (Err.number <> 0) thenWScript.Echo "Error: " & Err.Description

end if

if result thenWScript.Echo "Item Undeleted"

elseWScript.Echo "Item has not been Undeleted"

end if

Page 220: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

220 Content Management APIContent object

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

Syntaxinterface IContent : IDispatch

Member summary

Exampleitem.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);IContent content = item.Content;

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.

Page 221: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

221Content Management APIContent object

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

Page 222: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

222 Content Management APIIContent :: Title

IContent :: TitleThis property holds the name, title or subject of the item.

The property is read/write.

SyntaxHRESULT Title([out, retval] BSTR* pVal);HRESULT Title([in] BSTR newVal);

Parameters

RemarksIf an attempt is made to change the title after a call to Insert or Get, an error will occur.

Return value

Example

C#IContent content = itm.Content;string title = content.Title;

[out, retval] BSTR* pVal The title of this item.

[in] BSTR newVal The new title of this item.

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.

Page 223: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

223Content Management APIIContent :: OriginalLocation

IContent :: OriginalLocationThis property holds the original location of the item.

The property is read/write.

SyntaxHRESULT OriginalLocation([out, retval] BSTR* pVal);HRESULT OriginalLocation([in] BSTR newVal);

Parameters

Return value

Exampleitem.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);IContent content = item.Content;content.Title = "New title";content.FileExtension = "msg";content.OriginalLocation = “Inbox”;content.Data = "C:\\temp\\test.msg";item.Insert();

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

[in] BSTR newVal The original location value to be set.

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.

Page 224: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

224 Content Management APIIContent :: FileExtension

IContent :: FileExtensionThis property holds the file extension describing the format of the item.

The property is read/write.

SyntaxHRESULT FileExtension([out, retval] BSTR* pVal);HRESULT FileExtension([in] BSTR newVal);

Parameters

RemarksThis 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

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

[in] BSTR newVal The file extension to use.

S_OK Success.

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

Page 225: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

225Content Management APIIContent :: FileExtension

Exampleitem.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);IContent content = item.Content;content.Title = "New title";content.FileExtension = "msg";content.OriginalLocation = “Inbox”;content.Data = "C:\\temp\\test.msg";item.Insert();

Page 226: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

226 Content Management APIIContent :: MIMEFormat

IContent :: MIMEFormatThis 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.

SyntaxHRESULT MIMEFormat([out, retval] BSTR* pVal);HRESULT MIMEFormat([in] BSTR newVal);

Parameters

RemarksFor 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

Exampleitem.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);IContent content = item.Content;content.Title = "New title";content.MIMEFormat = "text/plain";content.OriginalLocation = “C:\\temp”;

[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

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.

Page 227: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

227Content Management APIIContent :: MIMEFormat

content.Data = "C:\\temp\\test.txt";item.Insert();

Page 228: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

228 Content Management APIIContent :: CreatedDate

IContent :: CreatedDateThis property contains the UTC date and time that the item was created.

The property is read/write.

SyntaxHRESULT CreatedDate([out, retval] VARIANT* pVal);HRESULT CreatedDate([in] VARIANT newVal);

Parameters

RemarksOnce this item has been archived it is not possible to change the value of this property.

Return value

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or either an attempt to modify the property value after the item has been archived has been made, or the data passed in is corrupt and of the wrong data type.

Page 229: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

229Content Management APIIContent :: CreatedDate

object obj = content.CreatedTime;DateTime dt = (DateTime)obj;

Page 230: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

230 Content Management APIIContent :: ModifiedDate

IContent :: ModifiedDateThis property contains the UTC date and time that the item was last modified.

The property is read/write.

SyntaxHRESULT ModifiedDate([out, retval] VARIANT* pVal);HRESULT ModifiedDate([in] VARIANT newVal);

Parameters

Return valueOnce this item has been archived it is not possible to change the value of this property.

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

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

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.

Page 231: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

231Content Management APIIContent :: ModifiedDate

DateTime dt = (DateTime)obj;

Page 232: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

232 Content Management APIIContent :: Data

IContent :: DataThis property is used to pass the raw content of the item to or from the archive.

The property is read/write.

SyntaxHRESULT Data([out, retval] VARIANT* pVal);HRESULT Data([in] VARIANT newVal);

Parameters

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

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the actual item data.

[in] VARIANT newVal Variant containing the data.

Page 233: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

233Content Management APIIContent :: Data

Handling items larger than 4MB prior to Enterprise Vault 8.0When using a version of the Enterprise Vault API runtime prior to Enterprise Vault 8.0, .NET applications should ensure the following recommendations are implemented in order to support the insertion or retrieval of items larger than 4MB:

■ The application's entry point, the Main method, is not set to use the COM single-threaded apartment (STA) model.

■ The application's entry point, the Main method, invokes CoInitializeSecurity via PInvoke, with the following parameter values:CoInitializeSecurity(NULL, -1, NULL, NULL, RPC_C_AUTHN_LEVEL_CALL, RPC_C_IMP_LEVEL_IDENTIFY, NULL, EOAC_NONE, NULL);

■ All use of the Content Management API is from threads set to use the COM single-threaded apartment; the Content Management API is not invoked from the application's entry point method.

Applications where these conditions cannot be met, such as Windows Forms applications, applications hosted by IIS, or any other executable where COM security has already been initialized to restrict remote access, cannot support insert or retrieval of items larger than 4MB.

Return value

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

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.

Page 234: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

234 Content Management APIIContent :: OriginalSize

IContent :: OriginalSizeThis property returns the size of the original item, in bytes, before it was archived.

The property is read only.

SyntaxHRESULT OriginalSize([out, retval] VARIANT* pVal);

Parameters

RemarksThis 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

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

[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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 235: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

235Content Management APIIContent :: Author

IContent :: AuthorThis property contains the author of the item.

The property is read/write and optional.

SyntaxHRESULT Author([out, retval] BSTR* pVal);HRESULT Author([in] BSTR newVal);

Parameters

RemarksThis 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

Example

C#[in]

item.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);IContent content = item.Content;content.Title = "New title";

[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

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.

Page 236: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

236 Content Management APIIContent :: Author

content.Author = “Charles Dickens”content.FileExtension = "msg";content.OriginalLocation = “Inbox”;content.Data = "C:\\temp\\test.msg";item.Insert();

[out]

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

IContent cont = item.Content;

string author = content.Author;

Page 237: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

237Content Management APIArchiveMetaData object

ArchiveMetaData objectThis object implements the following interfaces:

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

Syntaxinterface IArchiveMetaData : IDispatchinterface 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 canbe set.

OverrideOnHoldRetCat Read/Write This property is set TRUE to delete an item that Enterprise Vault will normally prevent because the Retention Category On-hold flag is enabled.

ArchivedDate Read only This property contains the UTC date and time that the

item was originally stored into the archive.

ComplianceData Read only This property returns a valid pointer to an instance ofthe IComplianceData interface that allows the caller toset compliance values for the archived item.

Page 238: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

238 Content Management APIArchiveMetaData object

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 APIcan 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 itemis deleted before the archive item is secured, then the item may not be restored as part of a disaster recoveryof the Enterprise Vault server.

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

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

CustomProperties Read/write This property can be used to hold proprietary information about the stored item.

Table 4-31 IArchiveMetaData method

Method Description

Update Used to apply ComplianceData changes to a stored item.

Table 4-30 IArchiveMetaData properties

Property Read/Write Description

Page 239: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

239Content Management APIArchiveMetaData object

Remarks

Version informationIArchiveMetaData2 interface requires Enterprise Vault 8.0.

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

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.

Page 240: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

240 Content Management APIIArchiveMetaData :: RetentionCategory

IArchiveMetaData :: RetentionCategoryThis property contains the name or Id of the retention category assigned to the item.

The property is read/write.

SyntaxHRESULT RetentionCategory([out, retval] BSTR* pVal);HRESULT RetentionCategory([in] BSTR newVal);

Parameters

RemarksAn example of this would be "Business" or any other retention category created using the Enterprise Vault Administrator Console.

The retention category Id may be specified as an alternative.

The Retention API can be used to discover or create retention categories.

See “Retention API” on page 387.

This property may be modified after the item has been archived.

Return value

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

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.

Page 241: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

241Content Management APIIArchiveMetaData :: RetentionCategory

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

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.

Page 242: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

242 Content Management APIIArchiveMetaData :: ComplianceDevice

IArchiveMetaData :: ComplianceDeviceThis property indicates whether the item is stored on a compliance device on which retention periods can be set.

The property is read only.

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

Parameters

RemarksA value of true is returned if this item is on a compliance device.

Return value

ExampleIItem 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

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which will contain the current value of this property

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 243: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

243Content Management APIIArchiveMetaData :: OverrideOnHoldRetCat

IArchiveMetaData :: OverrideOnHoldRetCatThis property enables deletion of an item even if the retention category on-hold flag is enabled.

The property is read/write.

SyntaxHRESULT OverrideOnHoldRetCat([out, retval] VARIANT_BOOL* pVal);HRESULT OverrideOnHoldRetCat([in] VARIANT_BOOL newVal);

Parameters

RemarksThis 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

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

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

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.

Page 244: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

244 Content Management APIIArchiveMetaData :: OverrideOnHoldRetCat

IArchiveMetaDate amd = item.ArcxhiveMetaData;amd.OverrideOnHoldRetCat = true;item.Insert();

[out]

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

IArchiveMetaData amd = item.ArchiveMetaData;

bool override = amd. OverrideOnHoldRetCat;

if (override == true){

//do something

Page 245: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

245Content Management APIIArchiveMetaData :: ArchivedDate

IArchiveMetaData :: ArchivedDateThis property contains the UTC date and time that the item was originally stored in the archive.

The property is read only.

SyntaxHRESULT ArchivedDate([out, retval] VARIANT* pVal);

Parameters

RemarksThis property is optional.

Version informationAt Enterprise Vault 8.0, this property becomes a read/write property.

See “IArchiveMetaData2 :: ArchivedDate” on page 275.

Return value

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

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived date of this item

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or the value input is not a valid date time..

Page 246: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

246 Content Management APIIArchiveMetaData :: ArchivedDate

DateTime dt = (DateTime) obj;

Page 247: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

247Content Management APIIArchiveMetaData :: ComplianceData

IArchiveMetaData :: ComplianceDataThis 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.

SyntaxHRESULT ComplianceData([out, retval] IComplianceData** pVal);

Parameters

RemarksAlthough this property itself is read-only, its own properties allow compliance data to be added/modified.

The IComplianceData interface enables compliance metadata to be set on an item in an archive.

See “ComplianceData object” on page 307.

Return value

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

IArchiveMetaData amd = item.ArchiveMetaData;

IComplinceData compData = amd.ComplianceData;

[out, retval] IComplianceData** pVal Pointer to a valid IComplianceData pointer.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 248: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

248 Content Management APIIArchiveMetaData :: ComplianceData

EV_STG_API_CP_UNITS evUnits = compData.Units;object obj = compData.Value;ulong val = (ulong)obj;

Page 249: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

249Content Management APIIArchiveMetaData :: SavesetSize

IArchiveMetaData :: SavesetSizeThis property holds the size of the archived item saveset, rounded to the nearest KB.

The property is read/write.

SyntaxHRESULT SavesetSize([out, retval] VARIANT* pVal);

Parameters

RemarksThis property is only available after an item has been archived. The VARIANT type of this property should be vt = VT_UI4.

Although it is marked as read/write, this property cannot be modified on an item that has already been archived.

Return value

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

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the current value of the property

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.

Page 250: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

250 Content Management APIIArchiveMetaData :: SavesetSize

ulong size = (ulong)obj;

Page 251: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

251Content Management APIIArchiveMetaData :: RetentionExpires

IArchiveMetaData :: RetentionExpiresThis property contains the UTC date and time when the item can be deleted from a compliance storage device.

The property is read only.

SyntaxHRESULT RetentionExpires([out,retval] VARIANT* pVal);

Parameters

RemarksThis property value is populated when the item detail level, DETAIL_LEVEL_COMPLIANCE_DATA, is set on the item Get method.

“EV_STG_API_ITEM_DETAIL enumeration” on page 65.

If the item is stored on a compliance device, then the property value is the UTC date and time when the item can be deleted from the device.

If the storage device is not a compliance device, then then the property value is 30/12/1899 00:00:00, which is equivalent to an Automation date of 0.

The VARTYPE of the variant should be vt = VT_DATE.

Return value

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 252: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

252 Content Management APIIArchiveMetaData :: RetentionExpires

IArchiveMetaData amd = item.ArchiveMetaData;

object obj = amd.RetentionExpires;DateTime dt = (DateTime)obj;

Page 253: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

253Content Management APIIArchiveMetaData :: IndexData

IArchiveMetaData :: IndexDataThis 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.

SyntaxHRESULT IndexData([out, retval] ISimpleIndexMetadata** pVal);

Parameters

RemarksThe properties and methods of the ISimpleIndexMetadata interface can also be used to add custom index data to an item as it is archived. The additional index data is then available in the archive's index.

The Search API can be used to find items with specific index properties and values.

For an overview of adding index properties to items, see “Adding custom index metadata” on page 55.

Return value

RequirementsRequires KVS.EnterpriseVault.Common.dll.

ExampleIArchiveMetaData amd = item.ArchiveMetaData;

[out, retval] ISimpleIndexMetadata** pVal Pointer to a SimpleIndexMetadata object.

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.

Page 254: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

254 Content Management APIIArchiveMetaData :: IndexData

ISimpleIndexMetadata simple = amd.IndexData;

See also■ “IItem :: Get” on page 200.

■ “SimpleIndexMetadata object” on page 277.

Page 255: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

255Content Management APIIArchiveMetaData :: IsItemSecured

IArchiveMetaData :: IsItemSecuredThis property indicates that is it safe to delete the original item from the source store.

The property is read only.

SyntaxHRESULT IsItemSecured([out, retval] VARIANT_BOOL* pVal);

Parameters

RemarksIf 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

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

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL which contains the current value of this property

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 256: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

256 Content Management APIIArchiveMetaData :: IsItemSecured

{//safe to delete original item from the source

Page 257: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

257Content Management APIIIArchiveMetaData :: CustomIdentifier

IIArchiveMetaData :: CustomIdentifierThis 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.

SyntaxHRESULT CustomIdentifier ([in] BSTR newVal); HRESULT CustomIdentifier ([out, retval] BSTR* pVal);

Parameters

RemarksThe 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

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

S_OK Success.

S_FALSE Success. The default value (NULL) is returned.

Page 258: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

258 Content Management APIIIArchiveMetaData :: CustomIdentifier

Example

Visual Basic ScriptThis example shows how CustomIdentifier, CustomQualifier and CustomProperties can be set.const CUSTOM_PROPERTIES = "<?xml version='1.0'?><properties><key = '1' value='some value'/></properties>"

const CUSTOM_ID = "AcmeWidgetId-00002"const CUSTOM_QUALIFIER = 1

Dim oItem

oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_IDoItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIESoItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER

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.

Page 259: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

259Content Management APIIIArchiveMetaData :: CustomQualifier

IIArchiveMetaData :: CustomQualifierThis 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.

SyntaxHRESULT CustomQualifier ([in] LONG newVal); HRESULT CustomQualifier ([out, retval] LONG* pVal);

Parameters

RemarksThis 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

[in] LONG newVal New value to set for this property.

[out, retval] LONG* pVal Pointer to a LONG containing the current value of this property.

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.

Page 260: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

260 Content Management APIIIArchiveMetaData :: CustomQualifier

Example

Visual Basic ScriptThis example shows how CustomIdentifier, CustomQualifier and CustomProperties can be set.const CUSTOM_PROPERTIES = "<?xml version='1.0'?><properties><key = '1' value='some value'/></properties>"

const CUSTOM_ID = "AcmeWidgetId-00002"const CUSTOM_QUALIFIER = 1

Dim oItem

oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_IDoItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIESoItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIER

Page 261: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

261Content Management APIIIArchiveMetaData :: CustomProperties

IIArchiveMetaData :: CustomPropertiesThis property can be used to hold proprietary information about the stored item.

The property is read/write.

SyntaxHRESULT CustomProperties ([in] BSTR newVal); HRESULT CustomProperties ([out, retval] BSTR* pVal);

Parameters

RemarksThe 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

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

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.

Page 262: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

262 Content Management APIIIArchiveMetaData :: CustomProperties

Example

Visual Basic ScriptThis example shows how CustomIdentifier, CustomQualifier and CustomProperties can be set.const CUSTOM_PROPERTIES = "<?xml version='1.0'?><properties><key = '1' cost='543'/></properties>"

const CUSTOM_ID = "AcmeWidgetId-00002"const CUSTOM_QUALIFIER = 1

Dim oItem

oItem.ArchiveMetaData.CustomIdentifier = CUSTOM_IDoItem.ArchiveMetaData.CustomQualifier = CUSTOM_QUALIFIERoItem.ArchiveMetaData.CustomProperties = CUSTOM_PROPERTIES

Page 263: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

263Content Management APIIArchiveMetaData :: Update

IArchiveMetaData :: UpdateThe Update method is used to effect changes made to the ICompliance interface by the calling application to the item stored in Enterprise Vault.

SyntaxHRESULT Update(void)

RemarksThe ArchiveId and Id properties must be set prior to calling the Update method.

The operation will only be performed if the compliance device allows it. If this is not the case, a bad HRESULT will be returned, indicating the cause of the failure.

Note the following when extending the compliance period on an item:

■ You cannot change the compliance period if the item is stored on a device that has no compliance period or does not support extending the compliance period.

■ The new retention period must be longer than the original retention period.

■ You can only extend the retention period of the retention category assigned to the item; you cannot assign a different retention category.

■ You cannot remove the compliance period completely by setting values to "NONE”.

■ The only values that can be changed currently are the compliance unit and value properties.

See “ComplianceData object” on page 307.

Return value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed in, or either the archive or item Id has not been set, or there is an error with the retention category, or an attempt has been made to change it.

CONTENTMANAGEMENTAPI_E_INVALID_DEVICE The storage device is not a compliance device.

Page 264: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

264 Content Management APIIArchiveMetaData :: Update

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

IArchiveMetaData amd = item.ArchiveMetaData;

IComplinceData compData = amd.ComplianceData;

compData.Units = EV_STG_API_CP. CP_UNITS_MONTHS;compData.Value = 18;

amd.Update();

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.

Page 265: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

265Content Management APIIArchiveMetaData2 :: CurrentLocation

IArchiveMetaData2 :: CurrentLocationThis 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.

SyntaxHRESULT CurrentLocation ([in] BSTR newVal); HRESULT CurrentLocation ([out, retval] BSTR* pVal);

Parameters

RemarksThe Items collection object can be used to populate this property automatically.

The property value is automatically populated by any of the following methods:

■ Insert

■ MoveTo

■ CopyTo

The folder path specifies the archive folder path relative to the root, or default, archive folder. The following examples illustrate the default root archive folder path used by the CurrentLocation property for the different types of archives:

■ Mailbox archives.

The CurrentLocation property value does not contain any folder path elements for the default root archive folder.

The example value “Inbox\Accounts” represents the location of an item in the folder “Accounts”, which is subfolder of “Inbox” archive folder.

■ Public Folder archives.

The default root archive folder path in the CurrentLocation property value represents the location of the Exchange Public Folder archiving target.

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

Page 266: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

266 Content Management APIIArchiveMetaData2 :: CurrentLocation

For example, if the folder path for an Exchange Public Folder archiving target is “EXCHSVR\Sales\Documents”, and the value of the CurrentLocation property is “EXCHSVR\Sales\Documents\FolderA”, then the item is located in the folder “FolderA”, which is subfolder of the root archive folder for the Public Folder archiving target.

■ FSA archives.

The default root archive folder path in the CurrentLocation property value represents the location of the FSA volume archiving target.

For example, if the folder path for an FSA volume archiving target is “\\FileSVR1.Example.COM\FSA Volume\5”, and the value of the CurrentLocation property is “\\FileSVR1.Example.COM\FSA Volume\5\NewFolder”, then the item is located in the folder “NewFolder”, which is subfolder of the root archive folder for the FSA volume archiving target.

■ SharePoint archives.

The default root archive folder path in the CurrentLocation property value represents the URL of the SharePoint site collection archiving target.

For example, if the URL for a SharePoint site collection archiving target is “http://sharepoint/sites/marketing”, and the value of the CurrentLocation property is “http://sharepoint/sites/marketing/UK”, then the item is located in the folder “UK”, which is subfolder of the root archive folder for the SharePoint site collection target.

Note that the syntax rules applied to SharePoint archive folder paths differ from those applied to folder paths in other types of archive.

The following syntax rules apply when retrieving or setting the CurrentLocation property value for archives other than SharePoint archives;

■ The backslash character (‘\’) is treated as the folder path subfolder separator character.

■ Double backslash (‘\\’) is used for preserving a backslash character in the folder path string.

■ Leading backslash characters will be ignored.

If the CurrentLocation property is specified for a flat archive (for example, shared or journal archives, which do not contain folders), then the property value returned is an empty string.

You can use the IArchive2::HasFolders property to determine if the archive is flat or has a folder structure.

Page 267: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

267Content Management APIIArchiveMetaData2 :: CurrentLocation

Which properties determine the current archive folderFor item insert, copy or move operations, each of the following properties can be used to set the archive folder:

■ IArchiveMetaData2::CurrentLocation

■ IArchiveMetaData2:: CurrentFolderId

■ IContent::OriginalLocation

The following conditions should be noted:

■ CurrentFolderId and CurrentLocation properties are only intended for use with archives that contain folders.

■ CurrentFolderId and CurrentLocation are mutually exclusive.

■ CurrentFolderId and CurrentLocation are optional.

■ When copying or moving an item, then the destination archive folder is defined by IArchiveMetaData2::CurrentLocation (if the source archive contains a folder structure), or IContent::OriginalLocation (if the source archive is flat). If neither of these properties is specified, then the root folder of the archive is used.

For insert, copy or move operations, if the value of ArchiveId is an archive folder ID, then the ArchiveId property can be used instead of CurrentFolderId or CurrentLocation to define the archive folder for the item.

■ If the folder identified by CurrentLocation (or IContent::OriginalLocation, when defaulting) has not yet been created, it is created automatically, together with any missing parent folders.

The caller must have write access on the destination archive in order to create new folders. When creating new folders, folder permissions are inherited from the parent folder.

■ If IContent::OriginalLocation property is omitted, the value is populated with the path of the item’s archive folder (insert operation), or the path of the item’s archive folder in the source archive (copy or move operation).

Methods to enumerate, create, delete (if empty) and update archive folders are not currently available. Also, caller applications cannot manage folder level permissions using the Content Management API.

Table 4-33 summarizes how the archive folder is determined when different combinations of the following properties are set:

■ IArchiveMetaData2::CurrentFolderId

■ IArchiveMetaData2::CurrentLocation

Page 268: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

268 Content Management APIIArchiveMetaData2 :: CurrentLocation

)

■ IContent::OriginalLocation

Table 4-33 Determining the target archive folder for insert, move and copy operations

ArchiveId Property

CurrentFolderId Property

CurrentLocation Property

OriginalLocation Property

Archived to 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 CurrentLocation or OriginalLocation property (Folder created as necessary – viz current refile behaviour)

Value of OriginalLocation property

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. (It must be a folder in the archive)

Path of the specifiedCurrentFolderId from the Directory

Archive ID Specified Not specified Specified Specified folder.(It must be a folder within the archive)

Value of OriginalLocation property

Archive ID Specified Specified Irrelevant Not supported; error with invalid arguments 2

Archive folder ID Not specified Not specified Not specified Folder specified in 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

Page 269: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

269Content Management APIIArchiveMetaData2 :: CurrentLocation

Return value

Archive folder ID Not specified Specified Not specified Folder matching CurrentLocation property. (Folder created as necessary)

Value of CurrentLocation property

Archive folder ID Not specified Specified Specified Folder matching CurrentLocation property. (Folder created as necessary)

Value of OriginalLocation property

Archive folder ID Specified Not specified Not specified Specified folder.(It must be a folder in the archive)

Path of the specifiedCurrentFolderId from the Directory

Archive folder ID Specified Not specified Specified Specified folder.(It must be a folder in the archive)

Value of OriginalLocation property

Archive folder ID Specified Specified Irrelevant Not supported; error with invalid arguments 2

1.(CopyTo and MoveTo) If OriginalLocation is not specified, then it is copied from the source item saveset value.2.Allowed if the archive folder ID associated with the specified CurrentLocation matches the specified CurrentFolderId value.

Table 4-33 Determining the target archive folder for insert, move and copy operations

ArchiveId Property

CurrentFolderId Property

CurrentLocation Property

OriginalLocation Property

Archived to folder…

Saveset OriginalLocation1

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.

Page 270: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

270 Content Management APIIArchiveMetaData2 :: CurrentLocation

Example

C++IItem* pItem = NULL;pCmAPI->get_Item(&pItem);

// Identify ArchiveID of archive in which item is storedCComBSTR ArchiveId (L”181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);pItem->put_ArchiveId(ArchiveId);

// Identify Id of stored itemCComBSTR ItemId (L” 161000000000000~200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”)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 locationCComBSTR CurrentLocation;CComQIPtr<IArchiveMetaData2> pAMD2(pAMD);pAMD2->get_CurrentLocation(&CurrentLocation);

Page 271: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

271Content Management APIIArchiveMetaData2 :: CurrentFolderId

IArchiveMetaData2 :: CurrentFolderIdThis 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.

SyntaxHRESULT CurrentFolderId ([in] BSTR newVal); HRESULT CurrentFolderId ([out, retval] BSTR* pVal);

Parameters

RemarksThe Items collection object populates this property automatically.

The property value is automatically populated by any of the following methods:

■ IItem::Insert

■ IItem::MoveTo

■ IItem::CopyTo

For item insert, copy or move operations on structured archives, each of the following properties can define the destination archive folder:

■ IArchiveMetaData2::CurrentLocation

■ IArchiveMetaData2:: CurrentFolderId

■ IContent::OriginalLocation

See “Which properties determine the current archive folder” on page 267.

If the CurrentFolderId property is specified for a flat archive (for example, shared or journal archives, which do not contain folders), then the property value is populated with the archive Id value after an Item property retrieval operation.

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

Page 272: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

272 Content Management APIIArchiveMetaData2 :: CurrentFolderId

You can use the IArchive2::HasFolders property to determine if the archive is flat or has a folder structure.

Return value

Example

C++IItem* pItem = NULL;pCmAPI->get_Item(&pItem);

// Identify ArchiveID of archive in which item is storedCComBSTR ArchiveId (L”181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);pItem->put_ArchiveId(ArchiveId);

// Identify Id of stored itemCComBSTR ItemId (L” 161000000000000~200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”)pItem->put_Id(ItemId);

pItem->Get(DETAIL_LEVEL_ARCHIVE_METADATA );

IArchiveMetaDatat* pAMD = NULL;pItem->get_ArchiveMetaData(&pAMD);

//Fetch the item’s current archive folder IDCComBSTR CurrentFolderId;

CComQIPtr<IArchiveMetaData2> pAMD2(pAMD);

pAMD2->get_CurrentFolderId(&CurrentFolderId);

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.

Page 273: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

273Content Management APIIArchiveMetaData2 :: SequenceNum

IArchiveMetaData2 :: SequenceNumThis property specifies the Index Sequence Number of the archived item.

The property is read only.

SyntaxHRESULT SequenceNum ([out, retval] ULONGLONG* pVal)

Parameters

RemarksThis property uniquely identifies the item in the archive. It can be used to identify the start Index Sequence Number when enumerating collections of archived items using the Items collection object.

See “IItems :: StartSequenceNum” on page 168.

The Items collection object populatesthis property automatically. This is useful for bulk moving or copying items.

The property value is automatically populated immediately after any of the following operations:

■ IItem::Insert

■ IItem::MoveTo

■ IItem::CopyTo

Enterprise Vault item sequence numbers are not always consecutive, as items may have expired or been deleted.

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

[out, retval] ULONGLONG* pVal The Index Sequence Number (ISN) of the archived item.

Page 274: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

274 Content Management APIIArchiveMetaData2 :: SequenceNum

Return value

Example

C#This example shows how to use the IArchiveMetaData2 interface to fetch the SequenceNUm property.Item.ArchiveId = "181E669473B52E64384C9A7D9EACA0E7E1110000evsite”;

Item.Id = "200808070000000~200808070940280000~Z~BFA0C1B1FAB1468DB822E2473B4AAB05"

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;

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 275: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

275Content Management APIIArchiveMetaData2 :: ArchivedDate

IArchiveMetaData2 :: ArchivedDateThis property enables the caller to retrieve and set the original archived date and time (UTC) for the item.

The property is read/write.

SyntaxHRESULT ArchivedDate([in] VARIANT newVal);HRESULT ArchivedDate([out, retval] VARIANT* pVal);

Parameters

RemarksSetting this property is optional. Typically it is only set to retain the archived date when copying or moving items.

Note: Setting the archived date can affect the item's retention period.

To specify an ArchivedDate when storing an item, set the ArchivedDate property value before calling the Insert method.

When copying or moving an item, the default action is to retain the item's archived date. To reset the achived date to the current date time, simply set a null value on the destination ArchiveMetadata object.

See “Specifying item property override values” on page 193.

Return value

[in] VARIANT newVal The required UTC date and timeto be set for this item

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the archived date of this item

S_OK Success.

S_FALSE Success. The default value (0) is returned.

Page 276: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

276 Content Management APIIArchiveMetaData2 :: ArchivedDate

ExampleIItem itemSrc = cmAPI.Item;IItem itemDst = cmAPI.Item;itemSrc.ArchiveId =“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”;itemSrc.Id =“334880000000000~200707251102240000~0~D3962A35951E4B03AE9CFB68AFE1218”;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);

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.

Page 277: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

277Content Management APISimpleIndexMetadata object

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

Syntaxinterface ISimpleIndexMetadata : IDispatch

Member summary

Table 4-34 ISimpleIndexMetadata properties

Property Read/Write Description

NewEnum Read only Enumerator which returns a standard enumerator to a collection of SimpleIndexProperty objects

DateTimesUTC Read/Write Sets or retrieves whether the date and time properties are input and output in UTC or local system time.

Table 4-35 ISimpleIndexMetadata methods

Method Description

Count Gives the number of custom index metadata properties for the current item.

Add Adds a value for a custom index property.

Clear Clears all properties from the SimpleIndexMetadata object for the current item.

ToXML Returns the metadata in XML format.

FromXML Loads a set of properties that have previously been defined and stored using the ToXML method.

ToLocalTime Converts a UTC time to local system time.

Page 278: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

278 Content Management APISimpleIndexMetadata object

RemarksThe type of properties returned in the collection can be controlled using the enumeration, EV_STG_API_ITEM_DETAIL, on the Get method of the IItem interface.

Examples

C#IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

VBScriptThe following VBScript excerpt gives an example of how metadata can be read from the instance returned by Content Management API:' Get the Index Metadata from the retrieved item Set IMData = oItem.ArchiveMetaData.IndexData

if (IMData.Count() = 0) thenWScript.Echo "No properties loaded!", vbOKOnly + vbExclamation,

"Index Metadata"Err.Clear

else'Use local system date/timesIMData.DateTimesUTC = false' Loop through the properties displaying the details of eachDim idxpropfor each idxprop in IMData

Dim propInfoDim pValpropInfo = "Set: " + idxprop.Set + vbCrLf + "Name: " +

idxprop.NamepropInfo = propInfo + vbCrlf + "Searchable: " +

CStr(idxprop.Searchable)propInfo = propInfo + vbCrlf + "Retrievable: " +

CStr(idxprop.Retrievable)pVal = idxprop.ValuepropInfo = propInfo + vbCrLf + "Value (" + TypeName(pVal) +

"): " + CStr(pVal)

ToUTCTime Converts a local system time to UTC time.

Table 4-35 ISimpleIndexMetadata methods

Method Description

Page 279: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

279Content Management APISimpleIndexMetadata object

WScript.Echo propInfo, vbOKOnly, "Index Metadata Properties List"

nextif (Err.number <> 0) then

WScript.Echo "Enumerating failed!" + vbCrLf + "Reason: " +Hex(Err.number) + vbCrLf + "Description: " +Err.Description, vbOKOnly + vbExclamation, "Index Metadata"

Err.Clearend if

end if

RequirementsImplemented in KVS.EnterpriseVault.Common.dll.

See also■ “SimpleIndexProperty object” on page 293.

■ “IItem :: Get” on page 200.

Page 280: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

280 Content Management APIISimpleIndexMetadata :: _NewEnum

ISimpleIndexMetadata :: _NewEnumThis 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.

SyntaxHRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters

RemarksThis 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

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

[out,retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive property value.

Page 281: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

281Content Management APIISimpleIndexMetadata :: _NewEnum

foreach (ISimpleIndexProperty ip in simple){

string set = ip.Set;string name = ip.Name;object val = ip.Value;bool searchable = ip.Searchable;bool retrievable = ip.Retrievable;

//do something with the values obtained}

Page 282: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

282 Content Management APIISimpleIndexMetadata :: DateTimesUTC

ISimpleIndexMetadata :: DateTimesUTCThis boolean property sets or retrieves whether the date and time properties are input and output in UTC or local system time.

SyntaxHRESULT DateTimesUTC([out, retval] VARIANT_BOOL* pRetVal);HRESULT DateTimesUTC([in] VARIANT_BOOL pRetVal);

Parameters

RemarksBy default, items are always archived using UTC time.

Return value

Examples'Use local system date/timesIMData.DateTimesUTC = false

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL.

Page 283: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

283Content Management APIISimpleIndexMetadata :: Count

ISimpleIndexMetadata :: CountThis method gives the number of custom index metadata properties for the current item.

SyntaxHRESULT Count([out, retval] long* pRetVal);

Parameters

Return value

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

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

if (simple.Count > 0){

//do something

[out, retval] long* pRetVal Number of custom index metadata properties.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL.

Page 284: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

284 Content Management APIISimpleIndexMetadata :: Add

ISimpleIndexMetadata :: AddThis 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.

SyntaxHRESULT Add

[in] BSTR propertySet,[in] BSTR propertyName,[in] VARIANT propertyValue, [in] VARIANT_BOOL propertySearchable,[in] VARIANT_BOOL propertyRetrievable);

Parameters

[in] BSTR propertySet Name of the property set to which the property belongs, or is to be added. If no property set is specified, the property is added to the default (global) property set.

[in] BSTR propertyName Name of the property.

[in] VARIANT propertyValue Property value. A Variant containing a value of any of the support types as follows:

Value type Variant type Note

String VT_BSTR

Datetime VT_DATE Limited to the UTC date range of 1st January 100 to 31st December 2148

Integer VT_UI1, VT_UI2, 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

Page 285: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

285Content Management APIISimpleIndexMetadata :: Add

RemarksCustom index data can only be added when the item is inserted, copied or moved. It is not possible to update custom index data for an archived item.

The method can be called repeatedly to add multiple properties or to add multiple values to the same property.

When you use Add to add a property to the index, the property will be added to the property set specified by the propertySet parameter.

If a property set is specified that does not exist, then the property set will be created and the property and value will be added to that new set.

It is good practice to use a named property set for properties added by an application in order to avoid name clashes with other custom additions. Suitable names would be your company name or the application name. The following property set names are reserved:

■ Vault

■ EnterpriseVault

■ Any property set name starting with EV

■ KVS

■ Veritas

■ Symantec

Return value

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

S_OK Success.

Page 286: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

286 Content Management APIISimpleIndexMetadata :: Add

Exampleitem.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);IContent content = item.Content;content.Title = "New title";content.FileExtension = "msg";content.OriginalLocation = “Inbox”;content.Data = "C:\\temp\\test.msg";IArchiveMetaDate amd = item.ArcxhiveMetaData;ISimpleIndexMetaData simple = amd.IndexData;

//add some custom index datasimple.Add(“My set”, “My name”, 32, true, true);

item.Insert();

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, forexample out of supported range.

Page 287: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

287Content Management APIISimpleIndexMetadata :: Clear

ISimpleIndexMetadata :: ClearThis method is used to clear all properties from the SimpleIndexMetadata object for the current item.

SyntaxHRESULT Clear();

Return value

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

S_OK Success.

Page 288: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

288 Content Management APIISimpleIndexMetadata :: ToXML

ISimpleIndexMetadata :: ToXMLThis method returns the metadata in XML format.

SyntaxHRESULT ToXML(

[in] VARIANT_BOOL formattedLayout, [out, retval] BSTR* pRetVal);

Parameters

Return value

ExamplesThe 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 NextDim ecmAPISet ecmAPI = CreateObject("EnterpriseVault.ContentManagementAPI")Dim oItemset oItem = ecmAPI.ItemoItem.ArchiveId = “137100ED24187DB43A884B0C0B8D3FF511110000EVServer”// populate the Data property from a fileoItem.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.IndexDataIMData.Clear‘ Use local date and time

[in] VARIANT_BOOL formattedLayout If true, the XML returned will be in human-readable format.

[out, retval] BSTR* pRetVal An XML string is returned.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL.

Page 289: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

289Content Management APIISimpleIndexMetadata :: ToXML

IMData.DateTimesUTC = false‘ Add a property called Agent, with the string value,‘ "EgApplication" to the default, global property set. This property‘ is searchable and retrievable.IMData.Add vbNullString, "Agent", "EgApplication",true, true

‘ Add the following properties to the property set called "EgApp".IMData.Add "Egapp", "File", "EgFilename", false, trueIMData.Add "EgApp", "TimeStamp", CDate("2006-10-23 12:00:00"), false, true

‘ return the property information as formatted XMLWScript.Echo IMData.ToXML(true)

oItem.Insert() // actually performs the insert...

The ToXML method in this example would display the custom metadata as formatted XML, as shown in Figure 4-3‚ ”ToXML result”.

Figure 4-3 ToXML result

See also■ “ArchiveMetaData object” on page 237

Page 290: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

290 Content Management APIISimpleIndexMetadata :: FromXML

ISimpleIndexMetadata :: FromXMLThis method enables you to load a set of properties that have previously been defined and stored using the ToXML method.

SyntaxHRESULT FromXML([in] BSTR xmlIndexMetadata);

Parameters

RemarksUse the Add method to add item specific values.

The XML schema is not published, as the Add method should always be used to add metadata properties.

Return value

Exampleitem.ArchiveId(“181E669473B52E64384C9A7D9EACA0E7E1110000evsite”);IContent content = item.Content;content.Title = "New title";content.FileExtension = "msg";content.OriginalLocation = “Inbox”;content.Data = "C:\\temp\\test.msg";IArchiveMetaDate amd = item.ArcxhiveMetaData;ISimpleIndexMetaData simple = amd.IndexData;

//add some custom index data from xml simple. FromXML(xmlData); //xmlData is a pre-populated string containing the xmlitem.Insert();

[in] BSTR xmlIndexMetadata The XML stream to input.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER xmlIndexMetadata supplied as NULL, or is invalid XML.

Page 291: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

291Content Management APIISimpleIndexMetadata :: ToLocalTime

ISimpleIndexMetadata :: ToLocalTimeThis is a helper method to convert a UTC time to local system time.

SyntaxHRESULT ToLocalTime(

[in] DATE utcDateTime, [out, retval] DATE* pRetVal);

Parameters

Return value

[in] DATE utcDateTime The UTC date and time to convert.

[out, retval] DATE* pRetVal The local date and time are returned.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL,or utcDateTime is not a syntactically valid UTC date time value.

Page 292: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

292 Content Management APIISimpleIndexMetadata :: ToUTCTime

ISimpleIndexMetadata :: ToUTCTimeThis is a helper method to convert a local system time to UTC date and time.

SyntaxHRESULT ToUTCTime(

[in] DATE localDateTime, [out, retval] DATE* pRetVal);

Parameters

Return value

[in] DATE localDateTime The local date and time to convert.

[out, retval] DATE* pRetVal The local date and time are returned.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER pRetVal is NULL,or localDateTime is not a syntactically valid local date time value.

Page 293: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

293Content Management APISimpleIndexProperty object

SimpleIndexProperty objectThe SimpleIndexProperty object implements the following interface:

■ ISimpleIndexProperty

Syntaxinterface ISimpleIndexProperty : IDispatch

Member summaryThis read-only interface has the following properties defined:

RemarksProperties added to the item index using the Add method of the ISimpleIndexMetadata interface are held as SimpleIndexProperty objects.

ExampleIArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

foreach (ISimpleIndexProperty ip in simple){

Table 4-36 ISimpleIndexProperty properties

Parameter Read/Write Description

Set Read only Name of the property set.

Name Read only Name of the property.

Value Read only Value assigned to the property.

Searchable Read only Whether the property is to be added to the item index.

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

System Read only Whether the property is one that is indexed by default during the archiving process.

Page 294: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

294 Content Management APIISimpleIndexProperty :: Set

ISimpleIndexProperty :: SetThis property returns the property set name.

The property is read only.

SyntaxHRESULT Set([out, retval] BSTR* value);

Parameters

RemarksIf empty, the property is a member of the global property set.

Return value

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

[out, retval] BSTR* value Property set name.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.

Page 295: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

295Content Management APIISimpleIndexProperty :: Set

//do something with the values obtained}

Page 296: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

296 Content Management APIISimpleIndexProperty :: Name

ISimpleIndexProperty :: NameThis property returns the property name.

The property is read only.

SyntaxHRESULT Name([out,retval] BSTR* value);

Parameters

RemarksThe name of a property can be a predefined name, such as IndexPropSUBJ, the numeric identification of an attachment (for example, 1.1), or a custom name.

If the value is a formatted number (1, 1.1, 1.2 and so on), then the property refers to a message attachment, which may be a file or a message. In this case, the value is another instance of a SimpleIndexMetadata object, detailing the index properties of the attachment.

If the property is a top-level message, then the Name is “1”. The first attachment would be “1.1”. The first attachment on a nested message would be “1.1.1”. Figure 4-4 illustrates the naming convention for messages and attachments.

Figure 4-4 Naming format for messages

[out,retval] BSTR* value Name of the property.

Top-level message

1

1.1 1.2

1.1.2 1.2.1

1.3

1.1.1

1.2.1.1

Message Attachments

Page 297: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

297Content Management APIISimpleIndexProperty :: Name

Each of the nested items has their own set of properties, which can be enumerated.

The property, IndexPropANUM, also contains the numeric identity of a message attachment. The value of this property differs from the property Name.

Figure 4-5 shows the values of IndexPropANUM for a message with an attached document and an attached message, which also has attached documents.

Figure 4-5 Example values of IndexPropANUM

If content items are missing, the COMR (content missing) property is returned in the index data. The value of this property indicates the reason for the missing content. For predefined values for this property, see “Note 4” on page 677.

Return value

Version information■ Numeric identity of a message attachments in IndexPropANUM is available

in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 31.

Top-level message

anum=0

anum=1 anum=4

anum=3 anum=5

anum=7

anum=2

anum=6

Message attachments

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.

Page 298: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

298 Content Management APIISimpleIndexProperty :: Name

■ Content missing reasons returned in the index data COMR property is available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 31.

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

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

IArchiveMetaData amd = item.ArchiveMetaData;

ISimpleIndexMetadata simple = amd.IndexData;

foreach (ISimpleIndexProperty ip in simple){

string set = ip.Set;string name = ip.Name;object val = ip.Value;bool searchable = ip.Searchable;bool retrievable = ip.Retrievable;

//do something with the values obtained}

See also■ “System properties” on page 664.

Page 299: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

299Content Management APIISimpleIndexProperty :: Value

ISimpleIndexProperty :: ValueThis property returns the property value.

The property is read only.

SyntaxHRESULT Value([out,retval] VARIANT* value);

Parameters

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

[out,retval] VARIANT* value Property value. A Variant containing a value of any of the support types as follows:

Value type Variant type Note

String VT_BSTR

Datetime VT_DATE Limited to the UTC date range of 1st January 100 to 31st December 2148

Integer VT_UI1, 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 An ISimpleIndexProperty instance

Page 300: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

300 Content Management APIISimpleIndexProperty :: Value

Return value

ExampleIItem 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}

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.

Page 301: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

301Content Management APIISimpleIndexProperty :: Searchable

ISimpleIndexProperty :: SearchableThis property returns whether the property is indexed, and hence can be searched for using the Search API.

The property is read only.

SyntaxHRESULT Searchable([out,retval] VARIANT_BOOL* value);

Parameters

Return value

ExampleIItem 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}

[out,retval] VARIANT_BOOL* value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.

Page 302: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

302 Content Management APIISimpleIndexProperty :: Searchable

See also■ “System properties” on page 664.

Page 303: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

303Content Management APIISimpleIndexProperty :: Retrievable

ISimpleIndexProperty :: RetrievableThis property returns whether the property can be retrieved and displayed with search results in the search application.

The property is read only.

SyntaxHRESULT Retrievable([out,retval] VARIANT_BOOL* value);

Parameters

Return value

ExampleIItem 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}

[out,retval] VARIANT_BOOL* value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.

Page 304: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

304 Content Management APIISimpleIndexProperty :: Retrievable

See also■ “System properties” on page 664.

Page 305: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

305Content Management APIISimpleIndexProperty :: System

ISimpleIndexProperty :: SystemThis property indicates that the property is an Enterprise Vault system property.

See “System properties” on page 664.

The property is read only.

SyntaxHRESULT System([out,retval] VARIANT_BOOL* value);

Parameters

RemarksFor custom properties that are added using Add, the value of System is always false.

Return value

ExampleIItem 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){

[out,retval] VARIANT_BOOL* value

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer was passed to receive property value.

Page 306: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

306 Content Management APIISimpleIndexProperty :: System

string set = ip.Set;string name = ip.Name;object val = ip.Value;bool searchable = ip.Searchable;bool retrievable = ip.Retrievable;bool isSystem = ip.System;

//do something with the values obtained}

See also■ “System properties” on page 664.

Page 307: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

307Content Management APIComplianceData object

ComplianceData objectThis object implements the following interface:

■ IComplianceData

The IComplianceData interface is obtained by using the ComplianceData property of the IArchiveMetaData interface.

Syntaxinterface IComplianceData : IDispatch

RemarksThe IComplianceData interface is for use only with compliance devices.

Member summary

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

IArchiveMetaData amd = item.ArchiveMetaData;IComplinceData compData = amd.ComplianceData;

Table 4-37 IComplianceData properties

Property Read/Write Description

Value Read/Write Combined with the Units property specifies the duration of the compliance period.

Units Read/Write Specifies the compliance period units, for example, days, weeks, months, years.

SetBy Write only Defines where the compliance period is set; the ComplianceData object, the retention category, or not set.

Page 308: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

308 Content Management APIIComplianceData :: Units

IComplianceData :: UnitsThis property, combined with the Value property, specifies the duration of the compliance period.

The property is read/write.

SyntaxHRESULT Units([out, retval] EV_STG_API_CP_UNITS* pVal);HRESULT Units([in] EV_STG_API_CP_UNITS newVal);

Parameters

RemarksEV_STG_API_CP_UNITS indicates the units used in specifying the compliance period.

See “EV_STG_API_CP_UNITS enumeration” on page 62.

Return value

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

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

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.

Page 309: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

309Content Management APIIComplianceData :: Units

IComplinceData compData = amd.ComplianceData;

EV_STG_API_CP_UNITS evUnits = compData.Units;object obj = compData.Value;ulong val = (ulong)obj;

Page 310: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

310 Content Management APIIComplianceData :: Value

IComplianceData :: ValueThis property, combined with the Units property, specifies the duration of the compliance period.

The property is read/write.

SyntaxHRESULT Value([out, retval] VARIANT* pVal);HRESULT Value([in] VARIANT newVal);

Parameters

RemarksThe 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

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

IArchiveMetaData amd = item.ArchiveMetaData;

IComplinceData compData = amd.ComplianceData;

[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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or newVal is invalid.

Page 311: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

311Content Management APIIComplianceData :: Value

EV_STG_API_CP_UNITS evUnits = compData.Units;object obj = compData.Value;ulong val = (ulong)obj;

Page 312: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

312 Content Management APIIComplianceData :: SetBy

IComplianceData :: SetByThis property indicates where the retention period was defined.

The property is write only.

SyntaxHRESULT SetBy([in] EV_STG_API_CP_SETBY newVal);

Parameters

RemarksEV_STG_API_CP_SETBY indicates where the compliance retention period is set.

See “EV_STG_API_CP_SETBY enumeration” on page 61.

This property should only be used during a copy/move operation and should not be called once an item has added to the archive.

Return value

[in] EV_STG_API_CP_SETBY newVal EV_STG_API_CP_SETBY containing the new value of the property

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER Invalid pointer passed to receive property value, or the value passed in does not conform to one of the enumeration type values.

Page 313: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

313Content Management APIHolds object

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

Syntaxinterface IHolds : IDispatchinterface IHolds2 : IHolds

About Legal HoldLegal Hold is the ability to prevent deletion of documents that are relevant to a legal case; items that are placed on hold cannot be deleted by a user or by Enterprise Vault (using storage expiry).

Legal Hold functionality is provided by the IHolds and IHold interfaces in the Content Management API. These interfaces allow Enterprise Vault Accelerator products and third-party applications to put items on hold, remove holds from items and enumerate all existing holds on an item.

Existing functionality in Discovery Accelerator allows the administrator to put items on hold.

Items can be placed on hold by specifying the following:

■ A Consumer ID, to identify the calling application.

■ A Group ID, to identify the group of items with a particular hold applied. The Group ID could, for example, identify the legal case.

■ Metadata, to provide additional information about the hold.

■ The list of items that the calling application wants to place on hold.

Page 314: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

314 Content Management APIHolds object

The metadata may be useful when there are several consumers of the Legal Hold API at the same time. For example, metadata could be used to say why one consumer has put the item on hold, and this information could then be accessed by other consumers. The metadata is in XML format, for example:<MetaData>

<Reason Value="John Doe against EG Corp" /></MetaData>

Using the IItem.Holds property, an application can enumerate all the holds which have been placed on an item; the API returns a list of holds (Hold IDs) on that item along with the metadata that was supplied when the item was put on hold.

Holds may be removed from items in two ways:

■ By specifying the Consumer ID and the Group ID. This will remove all holds which have been placed on an item with the supplied Consumer ID and Group ID.

■ By supplying the Consumer ID and a list of Hold IDs of items from which the consumer wants to remove holds. This allows the consumer to remove holds from items in batches rather than a whole group at once.

Member summary

Table 4-38 IHolds Properties

Property Description

_NewEnum This property gives access to an IEnumVariant interface (which acts an enumerator) and allows script clients to enumerate the collection of IHold interface pointers and iterate through the collection using a for...next loop.

Item This property gives access to a particular instance of IHold in the collection using the index.

Count This read only property returns the number of IHolds in the collection.

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

ConsumerGUID The ConsumerGUID is the unique identifier of the application calling the API.

Page 315: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

315Content Management APIHolds object

Version informationIHolds2 interface requires Enterprise Vault 8.0 SP1.

See also“Hold object” on page 332

Metadata The metadata property contains the metadata to be passed with the holds to the Enterprise Vault server. The same metadata will be applied to each hold in the group.

Table 4-39 IHolds Methods

Method Description

Add Adds an IHold interface pointer to the collection.

PlaceHolds Places a hold on each item in the collection.

ReleaseHolds Releases a hold on each item in the collection.

Table 4-40 IHolds2 Method

Method Description

ReleaseHolds2 Releases a hold on each item in the collection, and returns success or failure information, in XML format, for each vault store processed.

Table 4-38 IHolds Properties

Property Description

Page 316: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

316 Content Management APIIHolds :: _NewEnum

IHolds :: _NewEnumThis 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.

SyntaxHRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters

RemarksThis 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

ExampleIItem 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){

[out,retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER NULL pointer passed to receive property value.

Page 317: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

317Content Management APIIHolds :: Item

IHolds :: ItemThis property gives access to a particular hold in a collection.

The property is read/write.

SyntaxHRESULT Item([in] VARIANT index;HRESULT Item([out, retval] LPVARIANT pRetVal);

Parameters

RemarksThe 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

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

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

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.

Page 318: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

318 Content Management APIIHolds :: Count

IHolds :: CountThis read only property returns the number of Holds in the collection.

The property is read only.

SyntaxHRESULT Count([out, retval] long* pRetVal);

Parameters

Return value

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

[out, retval] long* pRetVal Current number of holds in the collection.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pRetVal pointer is NULL.

Page 319: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

319Content Management APIIHolds :: GroupId

IHolds :: GroupIdThis 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.

SyntaxHRESULT GroupId([in] BSTR newVal);HRESULT GroupId([out,retval] BSTR* pVal);

Parameters

RemarksThe 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

ExampleIHolds holds = cmAPI.Holds;

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

IHold hold = cmAPI.Hold;

[in] BSTR newVal BSTR containing the new group Id.

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

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.

Page 320: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

320 Content Management APIIHolds :: GroupId

hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;holds.Add(hold);

//add more hold’s if necessary

holds.PlaceHolds();

Page 321: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

321Content Management APIIHolds :: ConsumerGUID

IHolds :: ConsumerGUIDThis property is the unique identifier of the application calling the API.

The property is read only.

SyntaxHRESULT ConsumerGUID([in] BSTR newVal);HRESULT ConsumerGUID([out,retval] BSTR* pVal);

Parameters

RemarksThe 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

ExampleIHolds 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”;

[in] BSTR newVal BSTR containing any valid GUID value. Set by caller.

[out,retval] BSTR* pVal Pointer to a BSTR containing the current GUID

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.

Page 322: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

322 Content Management APIIHolds :: ConsumerGUID

holds.Add(hold);

//add more hold’s if necessary

holds.PlaceHolds();

Page 323: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

323Content Management APIIHolds :: Metadata

IHolds :: MetadataThis property contains the metadata to be passed with the holds to the Enterprise Vault server.

The property is read/write.

SyntaxHRESULT Metadata([in] BSTR newVal);HRESULT Metadata([out,retval] BSTR* pVal);

Parameters

RemarksThe same metadata will be applied to each hold in the group.

Return value

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

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER An attempt was made to modify this property once the PlaceHolds had been called.

Page 324: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

324 Content Management APIIHolds :: Metadata

//add more hold’s if necessary

holds.PlaceHolds();

Page 325: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

325Content Management APIIHolds :: Add

IHolds :: AddThis method allows a client to add a new hold to the collection.

SyntaxHRESULT Add([in] IHold* newHold);

Parameters

RemarksThe IHold interface pointer must be obtained through the IContentManagementAPI property, Hold.

Return value

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

.[in] IHold* newHold IHold interface pointer to add to the collection.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The Hold object has been used,or it has already been added with this Saveset Id, Transaction Id or Hold Id.

Page 326: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

326 Content Management APIIHolds :: PlaceHolds

IHolds :: PlaceHoldsThis function is used to actually place a hold on each item in the collection.

SyntaxHRESULT PlaceHolds();

RemarksAfter 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

ExampleIHolds 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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER A NULL pointer has been passed to receive the property value, or the hold is already placed, the groupId is missing, or there is an error with the ConsumerGUID.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

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

Page 327: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

327Content Management APIIHolds :: PlaceHolds

holds.PlaceHolds();

Page 328: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

328 Content Management APIIHolds :: ReleaseHolds

IHolds :: ReleaseHoldsThis function is used to release a hold on each item in the collection.

SyntaxHRESULT ReleaseHolds();

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

Page 329: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

329Content Management APIIHolds :: ReleaseHolds

ExamplecmAPI.DirectoryDNSAlias = “SERVER1”;

IHolds holds = cmAPI.Holds;holds.GroupId = “Group 1”;holds.ConsumerGUID = “{1D938946-329D-4bfa-87FF-9D30B808ADD1}”;holds.ReleaseHolds();

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

Page 330: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

330 Content Management APIIHolds2 :: ReleaseHolds2

IHolds2 :: ReleaseHolds2This 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.

SyntaxHRESULT ReleaseHolds2([out, retval] BSTR* pVal);

Parameters

RemarksThe IContentManagementAPI :: DirectoryDNSAlias property should be set by the caller before releasing holds by GroupId. This is required to identify the Enterprise Vault server hosting the directory that will be used to enumerate the Enterprise Vault Storage service computers that the group of holds spans.

When using a GroupId, if any of the holds in the group fail to be released, then the whole group is considered to have failed.

Note that some holds may actually have been released, but the caller will need to repeat the release on the group as whole until it succeeds, after establishing the reason for failure and correcting it.

When not using a GroupId, if the holds are spread over multiple vault stores, and any of the holds within a vault store fails to be released, all the holds in the vault store will also be marked as failed.

Finally, when all holds in a group are eventually released, then to dispose of the group itself, you must also call ReleaseHolds2( ) specifying the GroupId as before.

The XML returned by the method indicates the success or failure of the action for each vault store as a whole. In the XML, the vault store is identified by the Id field, and success or failure of the operation is indicated by the hr field (HRESULT). If the hold was released successfully on all affected items in a vault store, then the HRESULT returned for the vault store is 0. If the hold could not be released on some or all of the affected items in the vault store, then the hr field contains the error code value.

[out,retval] BSTR* pVal Pointer to a BSTR that will contain the status report in XML.

Page 331: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

331Content Management APIIHolds2 :: ReleaseHolds2

Version informationReleaseHolds2 method requires Enterprise Vault 8.0 SP1.

Return value

ExamplecmAPI.DirectoryDNSAlias = “SERVER1”;

IHolds2 holds = (IHolds2)cmAPI.Holds;holds2.GroupId = “Group 1”;holds2.ConsumerGUID = “{1D938946-329D-4bfa-87FF-9D30B808ADD1}”;string xml holds2.ReleaseHolds2();

The following example shows XML returned by ReleaseHolds2. The HRESULT returned for the second vault store is not zero, indicating that the attempt to release the hold on items in this vault store failed.<VaultStores>

<VaultStore Id="16918E349851B39307B57E2FC4603DDB21210000VS2.eg.com" hr="0"/>

<VaultStore Id="157E2F1B39307B86918E3498C4603DDB21210000VS2.eg.com" hr="0x80040300"/>

<VaultStore Id="1B39307B86918E3498557E2FC4603DDB21210000VS.eg.com" hr="0"/>

</VaultStores>

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.

Page 332: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

332 Content Management APIHold object

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

Syntaxinterface IHold : IDispatch

Member summary

RemarksBeing derived from IDispatch, this interface can be used by scripting languages.

Table 4-41 IHold properties

Property Description

ArchiveId This property specifies the ArchiveID where the item to which this hold object refers is stored. This property must be set before a hold is placed or released.

ItemId This property specifies the identifier of the item to which this hold object refers. This property must be set before a hold is placed.

Id This property identifies the hold object. It is returned once a hold has been placed, and must be set before a hold can be released.

Status This read only property returns the status of the hold after an attempt either to place or release a hold.

Metadata This read only property returns the metadata that is stored with the hold.

ConsumerGUID This read only property returns the unique identifier of the calling application that placed the hold.

GroupId This read only property returns the identifier of the group of holds to which the hold belongs.

Page 333: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

333Content Management APIHold object

ExampleIHold hold = cmAPI.Hold;hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;holds.Add(hold);

Page 334: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

334 Content Management APIIHold :: ArchiveId

IHold :: ArchiveIdThis property specifies the ArchiveID of the archive where the item that this hold object refers to is stored.

The property is read/write.

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

Parameters

RemarksThis property must be set before a hold is placed or released.

Return value

Example[in]

IHold hold = cmAPI.Hold;hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;holds.Add(hold);

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or the value is not a syntactically valid Archive Id.

Page 335: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

335Content Management APIIHold :: ArchiveId

[out]

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++){

IHold hold = (IHold)holds.Item(i + 1);

string archId = hold.ArchiveId;

Page 336: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

336 Content Management APIIHold :: ItemId

IHold :: ItemIdThis property specifies the identifier of the item to which the hold object refers.

The property is read/write.

SyntaxHRESULT ItemId([out, retval] BSTR* pVal);HRESULT ItemId([in] BSTR newVal);

Parameters

RemarksThis property must be set before a hold is placed.

The identifier can be a Saveset Id or a Transaction Id.

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

Return value

Example[in]

IHold hold = cmAPI.Hold;hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;hold.ItemId = 200501051649270000~0~9039eb282e3d4083b79f3298dc8a1e60”;holds.Add(hold);

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

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.

Page 337: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

337Content Management APIIHold :: ItemId

[out]

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++){

IHold hold = (IHold)holds.Item(i + 1);

string itemID = hold.ItemId;

Page 338: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

338 Content Management APIIHold :: Id

IHold :: IdThis property identifies the hold object.

The property is read/write.

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

Parameters

RemarksThe 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

Example[in]

IHolds holds = cmAPI.Holds;

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

IHold hold = cmAPI.Hold;

hold.ArchiveId = “1C9EFA88998592944ADB634ACC0D7410D1110000EVSite”;hold.Id = 123;

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL, or newVal is not a syntactically valid Hold Id.

Page 339: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

339Content Management APIIHold :: Id

holds.Add(hold);

//add more holds

holds.ReleaseHolds;

[out]

IHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++){

IHold hold = (IHold)holds.Item(i + 1);

string ID = hold.Id;

Page 340: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

340 Content Management APIIHold :: Status

IHold :: StatusThis property returns the status of the hold after an attempt to either place or release a hold.

The property is read only.

SyntaxHRESULT Status([out, retval] VARIANT* pVal);

Parameters

RemarksThe VARTYPE of the variant must be vt = VT_I4

Return value

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 341: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

341Content Management APIIHold :: Metadata

IHold :: MetadataThis property returns the metadata that is stored with the hold.

The property is read only.

SyntaxHRESULT Metadata([out, retval] BSTR* pVal);

Parameters

RemarksThis property is only populated when the IItem.Get method is called and the DetailLevel parameter includes the HoldData bit.

See “IItem :: Get” on page 200.

Return value

ExampleIHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++){

IHold hold = (IHold)holds.Item(i + 1);

string metadata = hold.MetaData;

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the metadata for this hold.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 342: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

342 Content Management APIIHold :: ConsumerGUID

IHold :: ConsumerGUIDThis property returns the unique identifier of the calling application that placed the hold.

The property is read only.

SyntaxHRESULT ConsumerGUID([out, retval] BSTR* pVal);

Parameters

RemarksThe 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

ExampleIHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++){

IHold hold = (IHold)holds.Item(i + 1);

string conGUID = hold.ConsumerGUID;

[out, retval] BSTR* pVal Pointer to a BSTR that will contain the consumer GUID of the application that placed the hold.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL,or pVal is not a valid GUID.

Page 343: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

343Content Management APIIHold :: GroupId

IHold :: GroupIdThis property returns the identifier of the group of holds to which the hold belongs.

The property is read only.

SyntaxHRESULT GroupId([out, retval] BSTR* pVal);

Parameters

RemarksSee “IHolds :: GroupId” on page 319.

Return value

ExampleIHolds holds = Item.Holds;

for (int i = 0; i < holds.Count ; i++){

IHold hold = (IHold)holds.Item(i + 1);

string groupID = hold.GroupId;

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The pVal pointer is NULL.

Page 344: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

344 Content Management APIICollectionBase : IDispatch

ICollectionBase : IDispatchThe 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.

Syntaxinterface ICollectionBase : IDispatch

Member summary

Version information■ This interface is available in Enterprise Vault 2007 or later.

Table 4-42 ICollectionBase properties

Property Read/Write Description

Count Read only Number of items in the collection.

_NewEnum Read only Instance of the standard COM enumerator for the collection.

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

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

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

Table 4-43 ICollectionBase methods

Method Description

Get Populate the collection.

Clear Clear the current collection.

Reset Reset the object back to the initial state.

Page 345: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

345Content Management APIICollectionBase :: Count

ICollectionBase :: CountThis property returns the current number of items in the collection.

The property is read only.

SyntaxHRESULT Count([out,retval] long* value);

Parameters

Return value

Example

C#archives.Get();for (long i = 0; i < archives.Count; i++){

ProcessArchive(archives.Item(i));

[out,retval] long* value Number of items in the collection.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL.

Page 346: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

346 Content Management APIICollectionBase :: _NewEnum

ICollectionBase :: _NewEnumThis 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.

SyntaxHRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters

RemarksThis 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

Example

C#archives.Get();foreach (IArchive archive in archives){

SearchArchive(archive.Id);

[out,retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER enumerator is NULL.

Page 347: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

347Content Management APIICollectionBase :: Item

ICollectionBase :: ItemThis 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.

SyntaxHRESULT Item([in] long index, [out,retval] IUnknown** item);

Parameters

Return value

Example

C#archives.Get();for (long i = 0; i < archives.Count; i++){

IArchive archive = (IArchive)archives.Item(i);SearchArchive(archive.Id);

[in] long index Zero-based index.

[out,retval] IUnknown** item Reference to an instance of the collection.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER item is NULL, or index is invalid.

Page 348: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

348 Content Management APIICollectionBase :: Maximum

ICollectionBase :: MaximumThis property sets the maximum number of items for the collection.

The property is read/write.

SyntaxHRESULT Maximum([out,retval] long* value);HRESULT Maximum([in] long value);

Parameters

RemarksThe 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

[out,retval] long* value Maximum number of items in the collection.

[in] long value Required maximum number of items for the collection.

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL, or value is invalid.

Page 349: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

349Content Management APIICollectionBase :: Maximum

Example

C#archives.Maximum = 6000;archives.Get();

Page 350: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

350 Content Management APIICollectionBase :: More

ICollectionBase :: MoreThis property indicates whether there were more items available in the collection than specified by Maximum.

The property is read only.

SyntaxHRESULT More([out,retval] VARIANT_BOOL* value);

Parameters

Return value

Example

C#archives.Maximum = 6000;

archives.Get();

if (archives.More == true){ //do something,

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

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER value is NULL.

Page 351: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

351Content Management APIICollectionBase :: Get

ICollectionBase :: GetThis method populates the collection with items that match the selection criteria up to the maximum number of items specified by Maximum.

SyntaxHRESULT Get(void);

RemarksAny existing collection is cleared prior to attempting to repopulate the collection.

Return value

Example

C#archives.Computer = ""EV1.acme.com";archives.Permissions =

EV_STG_API_PERMISSIONS_TYPE.PERMISSIONS_SEARCH;archives.ArchiveTypes =

EV_STG_API_ARCHIVE_TYPE.ARCHIVE_TYPE_SHARED;

S_OK Success.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER The combination of properties used for the collection selection criteria are invalid.

See “VaultStores object” on page 94,“Archives object” on page 109, or “Items object” on page 162.

CONTENTMANAGEMENTAPI_E_UNAVAILABLE The Enterprise Vault Directory or Storage services are not running.

CONTENTMANAGEMENTAPI_E_BUSY Enterprise Vault services are currently busy or do not have sufficient resources to complete the request. The request should be retried later, if there are insufficient resources the maximum number of records requested should be reduced.

Page 352: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

352 Content Management APIICollectionBase :: Get

archives.Get();

Page 353: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

353Content Management APIICollectionBase :: Clear

ICollectionBase :: ClearThis method clears the current collection.

SyntaxHRESULT Clear(void);

RemarksClears all items from the current collection setting it back to the empty state; Count returns zero.

Return value

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 setarchives.Clear();

S_OK Success.

Page 354: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

354 Content Management APIICollectionBase :: Reset

ICollectionBase :: ResetThis method resets the collection back to the initial empty state.

SyntaxHRESULT Reset(void);

RemarksAll items are cleared from the current collection, if any, and all selection criteria properties are reset back to their default empty values.

Return value

Examples

C#archives.Get();for (long i = 0; i < archives.Count; i++){ProcessArchive(archives.Item(i));}

//now reset archives before doing another get with different filters setarchives.Reset();

S_OK Success.

Page 355: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

355Content Management APIExtendedErrorInfo object

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

Syntaxinterface IExtendedErrorInfo : IDispatch

Member summary

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

Table 4-44 IExtendedErrorInfo properties

Property Read/Write Description

Error Read only The Content Management API return value associated with the most recent call to a Content Management API method.

Description Read only The description for the Content Management API return value.

InnerError Read only The associated internal return value.

InnerErrorDescription Read only The description for the internal return value.

Source Read only This property is not currently implemented.

Page 356: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

356 Content Management APIExtendedErrorInfo object

that the same error scenario will return the same inner error value with future versions of Enterprise Vault.

Version information■ This interface is available from Enterprise Vault 8.0 SP2.

ExamplesIn the following example, the additional information returned by the IExtendedErrorInfo interface shows that the Enterprise Vault server is in Backup Mode:

API Error Code: 0x80040302 (Ref: CONTENTMANAGEMENTAPI_E_BUSY)

API Error Description: Enterprise Vault is temporarily unable to process the request.The server is busy, or has insufficient resources, or is onlyable to read data due to ongoing backups. Wait a while and thentry again.

EV Internal Error Code: 0xC0041B85 (Ref STORAGE_E_VAULTSTORE_INBACKUPMODE)

EV Internal Error Description: The Vault Store is currently in Backup Mode.

C++ exampleThe following example code shows how the ExtendedErrorInfo object is used.

CComPtr<IContentManagementAPI4> pCMAPI;

CComPtr<IItem> pItem;

HRESULT hr = pItem->CopyTo(pDestItem);

if (FAILED(hr)){

HRESULT hrGLE (S_OK);CComPtr<IUnknown> pIUnkErrInfo;

hrGLE = pCMAPI->get_LastError(&pIUnkErrInfo);

if (SUCCEEDED(hrGLE)) {

CComQIPtr<IExtendedErrorInfo> pExtErrInfo(pIUnkErrInfo);

Page 357: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

357Content Management APIExtendedErrorInfo object

if (pExErrInfo != NULL)

{

HRESULT hrError = S_OK;HRESULT hrInnerError = S_OK;CComBSTR bsErrorDesc;CComBSTR bsInnerErrorDesc;

pExErrInfo->get_Error(&hrError);pExErrInfo->get_InnerError(&hrInnerError);pExErrInfo->get_Description(&bsErrorDesc);

pExErrInfo->get_InnerErrorDescription(&bsInnerErrorDesc);

// *** Use error infoAddExtendedErrorToLogFile(L"Failed to copy archived

item", hrError, bsErrorDesc, hrInnerError,bsInnerErrorDesc);

}

}}

VBScript exampleThe following example code shows how the ExtendedErrorInfo object is used.

private Sub ReportCMAPIError(byref ecmAPI)

dim oExtErrdim szErrorDesc, szInnerErrorDescdim vbError, vbExtErrordim Msg

Err.Clear

set oExtErr = ecmAPI.LastError

vbError = oExtErr.Error

vbExtError = oExtErr.InnerError

szErrorDesc = oExtErr.Description

szInnerErrorDesc = oExtErr.InnerErrorDescription

Msg = "***************************" & vbCrLf & vbCrLfMsg = Msg & "** CM API EXTENDED ERROR INFO" & vbCrLf & vbCrLfMsg = Msg & " Error Code: 0x" & Hex(vbError) & vbCrLf & vbCrLf

Page 358: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

358 Content Management APIExtendedErrorInfo object

Msg = Msg & " Error Description: " & szErrorDesc & vbCrLf &vbCrLfMsg = Msg & " InnerError Code: 0x" & Hex(vbExtError) & vbCrLf &vbCrLfMsg = Msg & " InnerError Description: " & szInnerErrorDesc &vbCrLf & vbCrLfMsg = Msg & "***************************"

WScript.Echo MsgErr.Clear

end sub

Page 359: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

359Content Management APIIExtendedErrorInfo :: Error

IExtendedErrorInfo :: ErrorThis 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.

SyntaxHRESULT Error([out, retval] long* pVal);

Parameters

RemarksFor a list of the return values, see “Content Management API return values” on page 685.

Return value

[out,retval] long* pVal Pointer to a long data type containing the Content Management API return value.

S_OK Success.

E_INVALIDARG pVal is Null.

Page 360: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

360 Content Management APIIExtendedErrorInfo :: Description

IExtendedErrorInfo :: DescriptionThis property provides the error description for the Content Management API return value.

This property is read only.

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

Parameters

RemarksThe error description strings are supplied in English only.

Return value

[out,retval] BSTR* pVal Pointer to a BSTR containing the error description.

S_OK Success.

E_INVALIDARG pVal is Null

Page 361: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

361Content Management APIIExtendedErrorInfo :: InnerError

IExtendedErrorInfo :: InnerErrorThis property provides the internal return value associated with the most recent call to a Content Management API method.

This property is read only.

SyntaxHRESULT InnerError([out, retval] long* pVal);

Parameters

RemarksThe inner error can be any Windows or Enterprise Vault COM return value. It is provided for additional information only, for example, to add to extended logging details.

The list of values is not documented, and it is not guaranteed that the same error scenario will return the same inner error value with future versions of Enterprise Vault.

Return value

[out,retval] long* pVal Pointer to a long data type containing the internal return value.

S_OK Success.

E_INVALIDARG pVal is Null

Page 362: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

362 Content Management APIIExtendedErrorInfo :: InnerErrorDescription

IExtendedErrorInfo :: InnerErrorDescriptionThis property provides the error description for the Enterprise Vault internal return value.

This property is read only.

SyntaxHRESULT InnerErrorDescription([out, retval] BSTR* pVal);

Parameters

RemarksThe error description strings are supplied in English only.

Return value

[out,retval] BSTR* pVal Pointer to a BSTR containing the error description.

S_OK Success.

E_INVALIDARG pVal is Null

Page 363: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

363Content Management APIIExtendedErrorInfo :: Source

IExtendedErrorInfo :: SourceThis property provides the GUID of the Content Management API object that was the source of the error information.

This property is read only.

SyntaxHRESULT Source([out, retval] GUID* pVal);

Parameters

RemarksThis property is not currently implemented, and returns E_NOTIMPL.

Return value

[out,retval] GUID* pVal GUID of the Content Management API object.

E_NOTIMPL Not implemented.

Page 364: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

364 Content Management APIDiagnosticsAPI object

DiagnosticsAPI objectThis 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).

Syntaxinterface IDiagnosticsAPI : IDispatch

Member summary

Remarks For a description of the Dtrace utility, see the Enterprise Vault Utilities guide.

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

Table 4-45 IDiagnosticsAPI properties

Property Read/Write Description

Name Read/Write Name of application

Table 4-46 IDiagnosticsAPI methods

Method Description

IsTraceEnabled Test whether trace is enabled for the selected level.

LogEvent Creates an entry in the Enterprise Vault event log.

Trace Traces a message, if trace enabled for the selected level.

Page 365: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

365Content Management APIIDiagnosticsAPI : Name

IDiagnosticsAPI : NameThis property holds the name of the application.

This property is read/write.

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

Parameters

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

then the log entry would appear something like…Application: Acme.RM

Failed to determine archive.Identity: John Paul JonesError: Entry Not Found (0x0002)

Return value

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

S_OK Success.

E_POINTER pVal is NULL, or is invalid.

E_ACCESSDENIED The property has already been set.

Page 366: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

366 Content Management APIIDiagnosticsAPI : IsTraceEnabled

IDiagnosticsAPI : IsTraceEnabledThis method tests whether tracing is enabled for the selected level.

SyntaxHRESULT IsTraceEnabled([in] EV_API_TRACE_LEVEL traceLevel,

[out, retval] VARIANT_BOOL* enabled);

Parameters

Remarks EV_API_TRACE_LEVEL is an enumerated value that indicates the level of tracing.

See “EV_API_TRACE_LEVEL enumeration” on page 59.

This method can be used to optimize the cost of building the trace message for the normal case, where trace is not enabled.

Return value

[in] EV_API_TRACE_LEVEL traceLevel EV_API_TRACE_LEVEL value to check.

[out, retval] VARIANT_BOOL* enabled Whether the trace level is enabled.

S_OK Success.

E_POINTER enabled is NULL.

Page 367: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

367Content Management APIIDiagnosticsAPI : LogEvent

IDiagnosticsAPI : LogEventThis method creates an entry in the Enterprise Vault event log.

SyntaxHRESULT LogEvent([in] EV_API_EVENT_TYPE eventType,

[in] BSTR message);

Parameters

Remarks EV_API_EVENT_TYPE is an enumerated value that indicates the type of event.

See “EV_API_EVENT_TYPE enumeration” on page 58.

The events are logged under a single Event Id, 7002. The event source is set to Enterprise Vault and the event category is determined by the executable logging the event. If the executable is not an Enterprise Vault executable then the category is None.

Return value

[in] EV_API_EVENT_TYPE eventType EV_API_EVENT_TYPE value.

[in] BSTR message Message to write.

S_OK Success.

E_INVALIDARG eventType is invalid or message is NULL.

Page 368: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

368 Content Management APIIDiagnosticsAPI : Trace

IDiagnosticsAPI : TraceThis method traces a message, if trace is enabled for the selected level.

SyntaxHRESULT Trace([in] EV_API_TRACE_LEVEL traceLevel,

[in] BSTR message);

Parameters

Remarks EV_API_TRACE_LEVEL is an enumerated value that indicates the trace level.

See “EV_API_TRACE_LEVEL enumeration” on page 59.

In the trace output, the application name is enclosed in brackets and prefixed to the trace message content to enable filtering in the DTrace utility. For example with Name set to the value Acme.RM, the message “Initialization complete” would appear as:4553 10:42:04.101 [5016] (AcmeRMServer) <4342> EV:L [Acme.RM] Initialization complete

Trace messages are captured dynamically by the Enterprise Vault DTrace utility if the component (that is, the executable) is enabled for tracing within the utility. The DTrace monitoring level setting for the component determines whether or not the Trace method generates a trace entry and hence whether or

[in] EV_API_TRACE_LEVEL traceLevel EV_API_TRACE_LEVEL value for trace level.

[in] BSTR message Trace message.

Page 369: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

369Content Management APIIDiagnosticsAPI : Trace

not the trace message is captured by the DTrace utility as shown in the table below.

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

Table 4-47 Mapping of API trace levels to Dtrace monitoring level settings

EV_API_TRACE_LEVEL value: TRACE_LEVEL_HIGH

TRACE_LEVEL_MEDIUM

TRACE_LEVEL_LOW

DTrace monitoringlevelsetting:

Off No No No

Brief Yes No No

Medium Yes Yes No

Verbose Yes Yes Yes

S_OK Success.

E_INVALIDARG message is NULL.

Page 370: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

370 Content Management APIIDiagnosticsAPI : Trace

Page 371: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

5

NSF Manager API

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

NSF Manager APIThe NSF Manager API interacts with the Content Management API to enable items in Notes databases to be stored in, or retrieved from, Enterprise Vault archives.

NSF Manager API creates and uses an NSF database file to hold data being passed to, or received from, the Content Management API.

The following steps outline how an application might use the NSF Manager and Content Management API to store a Note in an archive:

■ Use InitializeNotes to initialize the API.

■ Use SwitchToID to set the Notes security context (optional).

■ Use OpenNSF or CreateNSF to open or create an NSF database to hold the item to be stored.

■ Use ExportNote to export the item from the NSF database to the Content Management API.

The following Content Management API properties and method can then be used to store the item in an archive:

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

“IContent :: Data” on page 232.

■ IContent::FileExtension defines the type of the item (“dvns” or IContent.MIMEFormat = “application/x-evnotestream”).

Page 372: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

372 NSF Manager APINSF Manager API

See “IContent :: FileExtension” on page 224 and “IContent :: MIMEFormat” on page 226.

■ IItem::ArchiveId determines the destination archive for the item.

See “IItem :: ArchiveId” on page 175.

■ IItem::Insert stores the item in the archive.

“IItem :: Insert” on page 196.

■ Use DeleteNote to delete the note from the NSF database (optional).

■ Use CloseNSF to release the open NSF database.

■ Use TerminateNotes to terminate the NSF Manager API.

The following steps outline how an application can use the NSF Manager and Content Management API to retrieve a Note from an archive and view it in the Notes client:

■ Use InitializeNotes to initialize the API.

■ Use SwitchToID to set the Notes security context (optional).

■ Use OpenNSF or CreateNSF to open or create an NSF database to hold the item to be retrieved and viewed.

■ Use ImportNote to import the item from Content Management API to the NSF database.

The following Content Management API properties and method can be used to retrieve the item from the archive:

■ IItem::ArchiveId defines the archive where the item is stored.

See “IItem :: ArchiveId” on page 175.

■ IItem::Get retrieves the item from the archive.

See “IItem :: Get” on page 200.

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

“IContent :: Data” on page 232.

■ IContent::FileExtension specifies the type of the item (“dvns” or IContent::MIMEFormat = “application/x-evnotestream”).

See “IContent :: FileExtension” on page 224 and “IContent :: MIMEFormat” on page 226.

■ Use ViewNote to open the item in the Notes client.

■ Use DeleteNote to delete the item from the NSF database (optional).

■ Use CloseNSF to release the open NSF database.

■ Use TerminateNotes to terminate the NSF Manager API.

Page 373: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

373NSF Manager APINSF Manager API

ComponentsThe NSF Manager API contains one apartment-threaded, automation-friendly COM class:

■ NSFManager

SecurityWhen you interact with databases on a server, you must use an ID file that has appropriate permissions.

Page 374: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

374 NSF Manager APIEnumerations

EnumerationsThis section describes enumerations used by the NSF Manager API.

InitializeNotes enumerationInitializeNotes 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

};

Page 375: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

375NSF Manager APINSFManager object

NSFManager objectThe NSFManager object implements the following interface:

■ INSFManager

Syntaxinterface NSFManager : IDispatch

Member summary

RequirementsSee “Programming notes” on page 46.

Method Description

OpenNSF Opens an existing database.

CreateNSF Creates a new database.

CloseNSF Closes the open database and optionally deletes it.

ViewNote Launches the Notes client and opens the specified note.

ImportNote Imports a note from a file, or an IStream or ILockBytes object.

ExportNote Exports a note to a file, or an IStream or ILockBytes object.

DeleteNote Deletes the specified note.

InitializeNotes Initializes the Notes runtime on the main application thread, or on a worker thread.

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

SwitchToID Switches to the specified ID file.

CLSID FBD0FA42-EF3C-4761-B3E4-9C39422273CE

Prog ID KVS.EnterpriseVault.LotusDomino.NSFManager

Type Library EVContentManagementAPILib

DLL KVS.EnterpriseVault.NSFManager.dll

Page 376: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

376 NSF Manager APINSFManager object

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

.NET PIA namespace KVS.EnterpriseVault.Interop

Page 377: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

377NSF Manager APIINSFManager :: OpenNSF

INSFManager :: OpenNSFThis method opens an existing NSF database.

SyntaxHRESULT OpenNSF([in] BSTR bsFilePath);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] BSTR bsFilePath Specifies the full path to the database.

Page 378: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

378 NSF Manager APIINSFManager :: CreateNSF

INSFManager :: CreateNSFThis 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.

SyntaxHRESULT CreateNSF(

[in] BSTR bsTemplateName,[in] BSTR bsFilePath);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

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

Page 379: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

379NSF Manager APIINSFManager :: CloseNSF

INSFManager :: CloseNSFThis method closes the open NSF database and optionally deletes it.

SyntaxHRESULT CloseNSF([in] VARIANT_BOOL bDeleteNSF);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] VARIANT_BOOL bDeleteNSF Use VARIANT_TRUE to delete the database.Use VARIANT_FALSE to retain the database.

Page 380: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

380 NSF Manager APIINSFManager :: ViewNote

INSFManager :: ViewNoteThis method launches the Notes client and opens the specified note.

SyntaxHRESULT ViewNote([in] ULONG ulNoteId);

Parameters

Return valueS_OK (success) or standard COM error codes.

ExampleThe following example how to use ViewNote to open a note:

Type type = Type.GetTypeFromProgID("KVS.EnterpriseVault.LotusDomino.NSFManager");

INSFManager nsfMgr = (INSFManager)Activator.CreateInstance(type);

try{

nsfMgr.InitializeNotes(EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);

nsfMgr.OpenNSF(@"c:\DBs\TestDB.nsf");uint noteId = nsfMgr.ImportNote(@"c:\EVNotes\storedNote.dvns");nsfMgr.ViewNote(noteId);

}finally{

nsfMgr.CloseNSF(false);nsfMgr.TerminateNotes(

EV_NOTES_INIT_MODE.EV_NOTES_INIT_APPLICATION);}

[in] ULONG ulNoteId The ID of the note, which must exist in the database.

Page 381: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

381NSF Manager APIINSFManager :: ImportNote

INSFManager :: ImportNoteThis 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.

SyntaxHRESULT ImportNote(

[in] VARIANT vInputNote,[out, retval] ULONG *pulNoteId);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] VARIANT vInputNote Variant that contains the data to be imported.

[out, retval] ULONG *pulNoteId Returns the ID of the imported note.

Page 382: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

382 NSF Manager APIINSFManager :: ExportNote

INSFManager :: ExportNoteThis 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.

SyntaxHRESULT ExportNote(

[in] ULONG lNoteId,[in] VARIANT vOutputNote);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] ULONG ulNoteId The ID of the note.

[in] VARIANT vOutputNote A variant that contains the exported data.

Page 383: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

383NSF Manager APIINSFManager :: DeleteNote

INSFManager :: DeleteNoteThis method deletes the note from the NSF database.

SyntaxHRESULT DeleteNote([in] ULONG ulNoteId);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] ULONG ulNoteId The ID of the note.

Page 384: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

384 NSF Manager APIINSFManager :: InitializeNotes

INSFManager :: InitializeNotesThis 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.

SyntaxHRESULT InitializeNotes([in] EV_NOTES_INIT_MODE initMode);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to initialize on the main application thread or a worker thread.

Page 385: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

385NSF Manager APIINSFManager :: TerminateNotes

INSFManager :: TerminateNotesThis 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.

SyntaxHRESULT TerminateNotes([in] EV_NOTES_INIT_MODE initMode);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] EV_NOTES_INIT_MODE initMode Value of the enum, indicating whether to terminate on the main application thread or a worker thread.

Page 386: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

386 NSF Manager APIINSFManager :: SwitchToID

INSFManager :: SwitchToIDThis 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.

SyntaxHRESULT SwitchToID(

[in] BSTR bsIdFilePath,[in] BSTR bsPassword);

Parameters

Return valueS_OK (success) or standard COM error codes.

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

[in] BSTR bsIdFilePath The full path and file name of the ID file.

[in] BSTR bsPassword The ID file’s password.

Page 387: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

6

Retention API

This chapter describes the Enterprise Vault Retention API and its interfaces, methods and properties.

Retention APIThe Retention API enables management of the set of Enterprise Vault retention categories. An application using the Content Management API to archive items or an application using the Filtering APIs can use the Retention API to select an existing retention category, or create a new retention category.

The Retention API enables client applications to:

■ Create a new retention category.

■ Update an existing retention category.

■ Retrieve the details of an existing retention category.

■ Enumerate retention categories.

ComponentsThe API consists of two apartment-threaded, automation-friendly COM classes:

■ RetentionCategories

RetentionCategories implements a collection object of class RetentionCategory. It implements the IRetentionCategories and IRetentionCategories2 interfaces. The methods and properties enable the calling application to enumerate the current list of retention categories and add new retention categories.

■ RetentionCategory

The RetentionCategory class maintains a collection of RetentionCategory properties. It implements the IRetentionCategory and IRetentionCategory2

Page 388: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

388 Retention APIRetention API

interfaces. The methods and properties enable the calling application to view and change the various attributes of a retention category.

SecurityNo special privileges are required to list and read retention categories.

To create or update retention categories requires that the API is run under the Vault Service Account, or an account that is in a suitable Enterprise Vault roles-based administration role that includes the role task “EVT Administer Enterprise Vault Retention Categories”.

Page 389: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

389Retention APIEnumerations

EnumerationsThis section describes enumerations used by the Retention API.

Retention Units enumerationThe RetentionUnits value indicates the type of units used to define the retention period.enum _RetentionUnits {

Days = 0,Weeks = 1,Months = 2,Years = 3

};

Retention Date Basis enumerationThe RetentionDateBasis value indicates the date from which to calculate the storage expiry date of an item.enum _RetentionDateBasis {

ExpiryBasisArchiveDate = 0,ExpiryBasisModifiedDate = 1,ExpiryBasisInherit = 2,ExpiryBasisUnknown = 3

} ;

ExpiryBasisInherit takes the value set for the Enterprise Vault site.

The retention category cannot be saved or updated if the value set is ExpiryBasisUnknown.

Page 390: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

390 Retention APIRetentionCategories object

RetentionCategories objectThe RetentionCategories object implements the following interfaces:

■ IRetentionCategories

■ IRetentionCategories2 (default)

The interfaces implement a collection object for the creation and enumeration of RetentionCategory objects.

The IRetentionCategories2 interface inherits the properties and methods of the IRetentionCategories interface, and also provides a Get method to retrieve the properties of a retention category.

Syntaxinterface IRetentionCategories : IDispatchinterface IRetentionCategories2 : IRetentionCategories

Member summary

Table 6-1 IRetentionCategories properties

Property Read/Write Description

Count Read only The number of retention categories in the collection.

_NewEnum Read only An IEnumVariant interface pointer that is used to enumerate the collection of retention categories.

Item Read/Write This property returns the nth retention category object in the collection.

DirectoryDNSAlias Write only Identifies an Enterprise Vault server running an Enterprise Vault Directory Service.

Page 391: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

391Retention APIRetentionCategories object

RemarksTo ensure all available retention category properties can be retrieved, use the Add method to create a new retention category, and the Get method to retrieve details of a retention category.

The DirectoryDNSAlias property identifies an Enterprise Vault server that can be used to access the Enterprise Vault Directory for retention category information.

Table 6-2 IRetentionCategories methods

Method Description

Lookup Retrieve limited details of a retention category. This method is deprecated, as it does not return all available properties. Use the Get method to retrieve all properties of a retention category.

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

Add Add a retention category to the collection. This is the preferred method for creating a new retention category.

Update Update details of an existing retention category.

Table 6-3 IRetentionCategories2 method

Method Description

Get Retrieve details of a retention category.

Page 392: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

392 Retention APIRetentionCategories object

RequirementsSee “Programming notes” on page 46.

CLSID 744FC7D7-6933-4696-AC3F-9EFC1E00C96B

Prog ID EnterpriseVault.RententionCategories

Type Library RetentionAPILib

DLL EVRetentionAPI.dll

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

.NET PIA namespace KVS.EnterpriseVault.Interop

Page 393: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

393Retention APIIRetentionCategories :: Count

IRetentionCategories :: CountThis property returns the number of retention categories in the collection.

The property is read only.

SyntaxHRESULT Count([out, retval] long *plCount);

Parameters

Return value

ExamplesThe following example Visual Basic script enumerates the available retention categories. Dim oRCs Dim oRCDim sNamesDim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")if Err.Number <> 0 then

MsgBox(Err.Description)else

oRCs.DirectoryDNSAlias = "EVSite"MsgBox("There are " & oRCs.Count & " categories")For Each oRC In oRCs

sMsg = "Category is " & oRC.Name & " ; IsVisible=" &oRC.IsVisible & " ;

OnHold=" & oRC.OnHold & " ; Locked=" & oRC.LockedMsgBox(sMsg)sNames = sNames & " " & oRC.Name

Nextset oRCS = NothingMsgBox("The list is: " & sNames)

end if

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

S_OK Success.

E_POINTER The plCount pointer is NULL.

Page 394: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

394 Retention APIIRetentionCategories :: _NewEnum

IRetentionCategories :: _NewEnumThis property returns an IEnumVARIANT interface on an object that can be used to enumerate the collection of retention categories. This property is hidden in Visual Basic and Visual Basic Scripting Edition (VBScript).

The property is read only.

SyntaxHRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters

RemarksThis property is a standard property used to support enumerating collections, it is automatically used internally when you use the For Each construct in .NET managed code or VBScript.

This property returns a collection of RetentionCategory objects.

Return value

ExampleDim oRCs Dim oRCDim sNamesDim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")if Err.Number <> 0 then

MsgBox(Err.Description)else

oRCs.DirectoryDNSAlias = "EVSite"

[out,retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.

S_OK Success.

E_POINTER The pointer to the IUnknown pointer passed to the property is invalid.

Page 395: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

395Retention APIIRetentionCategories :: _NewEnum

MsgBox("There are " & oRCs.Count & " categories")For Each oRC In oRCs

sMsg = "Category is " & oRC.Name & " ; IsVisible=" &oRC.IsVisible & " ;

OnHold=" & oRC.OnHold & " ; Locked=" & oRC.LockedMsgBox(sMsg)sNames = sNames & " " & oRC.Name

Nextset oRCS = NothingMsgBox("The list is: " & sNames)

end if

Page 396: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

396 Retention APIIRetentionCategories :: Item

IRetentionCategories :: ItemThis property returns the nth retention category object in the collection.

The property is read/write.

Syntaxpropget] HRESULT Item([in] long index, [out, retval] VARIANT* pVal);

Parameters

RemarksThis method enables an alternative method of enumerating the retention categories in the collection.

Return value

ExampleIRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

[in] long Index Long containing the index value of the required item. The index is 1-based.

[out, retval] VARIANT* pVal Pointer to a VARIANT that will contain the retention category interface pointer requested.

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG Index is less than or greater than the collection count.

Page 397: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

397Retention APIIRetentionCategories :: DirectoryDNSAlias

IRetentionCategories :: DirectoryDNSAliasThis property is used to identify a computer running an Enterprise Vault Directory Service, in order to retrieve information from the Enterprise Vault Directory.

The property is write only.

SyntaxHRESULT DirectoryDNSAlias([in] BSTR bstrVal);

Parameters

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

HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\SiteID

The Id of an archive can be found in the Enterprise Vault Administration Console, in the properties dialog for an archive.

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

If you do not set DirectoryDNSAlias, then connection to the local computer is assumed.

Return value

[in] BSTR bstrVal The value can be any one of the following:

■ DNS alias of a computer hosting an Enterprise Vault Directory Service.

■ IP address of a computer hosting an Enterprise Vault Directory Service.

■ Id of the Enterprise Vault Site.

■ Id of any archive in the Site.

■ Id of any vault store in the Site.

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

Page 398: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

398 Retention APIIRetentionCategories :: DirectoryDNSAlias

ExamplesThe following example sets a value for DirectoryDNSAlias in order to list retention categories on a remote Enterprise Vault server. Dim oRCsDim oRCDim sNamesDim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")

if Err.Number <> 0 thenMsgBox(Err.Description)

elseoRCs.DirectoryDNSAlias = "ourvaultsite.domain.com"MsgBox("There are " & oRCs.Count & " categories")For Each oRC In oRCs

sMsg = "Category is " & oRC.Name & " ; IsVisible=" &oRC.IsVisible & " ; OnHold=" & oRC.OnHold & " ;

Locked=" & oRC.LockedMsgBox(sMsg)sNames = sNames & " " & oRC.Name

Nextset oRCS = NothingMsgBox("The list is: " & sNames)

end if

SiteIdNotFound bstrValue does not identify an existing site.

Page 399: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

399Retention APIIRetentionCategories :: Lookup

IRetentionCategories :: LookupThis method is used to obtain details of a retention category when the Name or Id of the retention category is known.

As this method does not return all available retention category properties, we recommend that you use the Get method instead.

SyntaxHRESULT Lookup([in] BSTR NameOrId,

[out] VARIANT *Period, [out] VARIANT *Units, [out] VARIANT *IsVisible, [out] VARIANT* Id, [out] VARIANT* RCName, [out, retval] VARIANT* RCFound);

Parameters

.[in] BSTR NameOrId String containing name or Id of the retention category.

[out] VARIANT *Period Value of Period for the retention category. This is the number of retention units an item is to be retained.

[out] VARIANT *Units Value of Units for the retention category. This is the type of retention units (days, weeks, months, years).

[out] VARIANT *IsVisible Value of IsVisible for the retention category. Describes whether the retention category is to be displayed to end users.

[out] VARIANT* Id Identifier of the retention category.

[out] VARIANT* RCName Name of the retention category. Identifies the retention category to the end user and the administrator.

[out, retval] VARIANT* RCFound A boolean return value that indicates whether or not the lookup was successful.

Page 400: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

400 Retention APIIRetentionCategories :: Lookup

Return value

ExamplesThe following example Visual Basic script looks up the values assigned to the Public retention category.Dim oAPIDim msg

Set oAPI = CreateObject("EnterpriseVault.RetentionCategories")

Dim id, name, units, period, isvisible

oAPI.Lookup "Public", period, units, isvisible, id, nameset oAPI = Nothing

msg = msg & " name = " & namemsg = msg & " period = " & periodmsg = msg & " units = " & unitsmsg = msg & " isvisible = " & isvisiblemsg = msg & " id = " & id

Msgbox(msg)

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

Page 401: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

401Retention APIIRetentionCategories :: Create

IRetentionCategories :: CreateThis method is used to create a new retention category.

As this method does not allow the specification of all available retention category properties, we recommend that you use the Add method instead.

SyntaxHRESULT Create([in] BSTR Name,

[in] LONG Period, [in] RetentionUnits Units, [in] VARIANT_BOOL IsVisible, [in] BSTR Description, [out,retval] BSTR* Id);

Parameters

RemarksIf the value of Period is 999999, and the value of Units is Years, the retention period is “forever”.

If IsVisible is false, the retention category is still visible in the Enterprise Vault Administration Console.

This method does not allow you to set a specific value for the ExpiryBasis property; the default value for the Enterprise Vault site will be used.

.[in] BSTR Name The name of the retention category.

[in] LONG Period Number of retention units items are to be retained.

[in] RetentionUnits Units Enumeration value for type of retention units (days, weeks, months, years).

See “Retention Units enumeration” on page 389.

[in] VARIANT_BOOL IsVisible Determines whether or not the retention category will be available to users for selection in manual archive operations.

[in] BSTR Description Description of the retention category.

[out,retval] BSTR* Id Retention category Id.

Page 402: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

402 Retention APIIRetentionCategories :: Create

Return value

ExampleIRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.Create(“New business”,10, RetentionUnits.Months, false, “New business correspondence”);

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

E_INVALIDARG One of the parameters is incorrect.

RetentionCategoryAlreadyExists A retention category with the same name already exists

Page 403: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

403Retention APIIRetentionCategories :: Add

IRetentionCategories :: AddThis is the preferred method for creating a new retention category and adding it to the collection object.

SyntaxHRESULT Add([in] IUnknown* RetentionCategory);

Parameters

RemarksAn error will be returned if a retention category already exists with the same name.

If the value of Period is 999999, and the value of Units is Years, the retention period is “for ever”.

Return value

ExamplesThe following example Visual Basic script adds two new retention categories: Finance and Legal. Dim oRCSDim oRC

Set oRCS = CreateObject("EnterpriseVault.RetentionCategories")

.[in] IUnknown* RetentionCategory A reference to a RetentionCategory object.

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

E_INVALIDARG One of the properties of the IRentionCategory pointer is invalid.

E_NOINTERFACE There is a problem with the IRetentionCategory pointer passed into the method.

RetentionCategoryAlreadyExists A retention category with the same name already exists

Page 404: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

404 Retention APIIRetentionCategories :: Add

'Create a Retention Category

Set oRC = NothingSet oRC = CreateObject("EnterpriseVault.RetentionCategory")

oRC.Name = "Finance"oRC.Description = "For finance dept items"oRC.Units = 3oRC.Period = 6oRC.IsVisible = TrueoRC.OnHold = FalseoRC.Locked = False

oRCS.Add(oRC)

msgbox(oRC.identifier)

'Create another Retention Category

Set oRC = NothingSet oRC = CreateObject("EnterpriseVault.RetentionCategory")

oRC.Name = "Legal"oRC.Description = "For legal department items"oRC.Units = 3oRC.Period = 7oRC.IsVisible = FalseoRC.OnHold = TrueoRC.Locked = True

oRCS.Add(oRC)

msgbox(oRC.identifier)

Page 405: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

405Retention APIIRetentionCategories :: Update

IRetentionCategories :: UpdateThis method is used to change an existing retention category.

SyntaxHRESULT Update([in] IUnknown* RetentionCategory);

Parameters

RemarksAny changes that you make to a retention category will be retrospective, and be applied to unexpired items that have been archived with the retention category.

An error will be returned if the retention category specified does not exist.

Return value

ExamplesThe following example updates details of retention categories on a remote computer and sets all the retention categories on hold.Dim oRCsDim oRCDim sNamesDim sMsg

Set oRCs = CreateObject("EnterpriseVault.RetentionCategories")

if Err.Number <> 0 thenMsgBox(Err.Description)

.[in] IUnknown* RetentionCategory Reference to the RetentionCategory object to be updated.

S_OK Success.

E_UNEXPECTED An unexpected error has occurred.

E_INVALIDARG One of the properties of the IRetentionCategory pointer passed as a parameter is invalid.

RetentionCategoryNotExist The retention category does not exist.

Page 406: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

406 Retention APIIRetentionCategories :: Update

elseoRCs.DirectoryDNSAlias = "ourvaultsite.domain.com"MsgBox("There are " & oRCs.Count & " categories")For Each oRC In oRCs

sMsg = "Category is " & oRC.Name & " ; IsVisible=" &oRC.IsVisible & " ; OnHold=" & oRC.OnHold & " ;Locked=" & oRC.Locked

MsgBox(sMsg)oRC.OnHold = trueoRCs.Update(oRC)sNames = sNames & " " & oRC.Name

Nextset oRCS = NothingMsgBox("The list is: " & sNames)

end if

Page 407: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

407Retention APIIRetentionCategories2 :: Get

IRetentionCategories2 :: GetThis is the preferred method for obtaining details of a retention category. It returns a populated instance of the RetentionCategory object.

SyntaxHRESULT Get([in] BSTR NameOrId,

[out, retval] IUnknown** RetentionCategory);

Parameters

RemarksThis method supercedes the Lookup method as it enables the retrieval of all available retention category properties, including the ExpiryBasis property.

Return value

ExampleIRetentionCategories2 retCats2 = (IRetentionCategories2) new RetentionCategoriesClass();

IRetentionCategory retcat = (IRetentionCategory)retCats2.Get(“Business”);

[in] BSTR NameOrId String containing name or Id of the retention category.

S_OK Success.

E_INVALIDARG NameOrId is NULL or RetentionCategory is NULL.

E_UNEXPECTED An unexpected error has occurred.

RetentionCategoryNotExist A Retention Category with the given NameOrId value does not exist.

Page 408: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

408 Retention APIRetentionCategory object

RetentionCategory objectThe RetentionCategory object implements the following interfaces:

■ IRetentionCategory

■ IRetentionCategory2 (default)

The interfaces maintain a set of properties for a RetentionCategory object. The IRetentionCategory2 interface inherits the properties and methods of the IRetentionCategory interface, and also provides the ExpiryBasis property.

Syntaxinterface IRetentionCategory : IDispatchinterface IRetentionCategory2 : IRetentionCategory

Member summary

Table 6-4 IRetentionCategory properties

Property Read/Write Description

Period read/write This property describes the number of retention units (days, weeks, months, years) an item is to be retained.

Units read/write This property describes whether the period has been expressed in days, weeks, months or years.

IsVisible read/write This property describes whether the category is to be displayed to end users.

Identifier read/write This property uniquely identifies the retention category.

Name read/write This property identifies the retention category to the end user and the administrator.

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

OnHold read/write This property describes whether archived items with a particular retention category can be deleted or expired. This protection applies during the retention period, and also after the retention period has expired.

This retention category hold is different from the Legal Hold API.

Page 409: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

409Retention APIRetentionCategory object

RemarksA RetentionCategory pointer can either be obtained using CoCreateInstance (or the equivalent in .NET or Visual Basic), or by obtaining one from the collection held in an instance of RetentionCategories.

Requirements

Locked read/write This property enables a lock to be put on a retention category. This prevents an administrator from inadvertently modifying the retention category.

Table 6-5 IRetentionCategory2 property

Property Read/Write Description

ExpiryBasis read/write This property indicates the date from which to calculate the storage expiry date of an item.

Table 6-4 IRetentionCategory properties

Property Read/Write Description

CLSID 333D8892-6804-4090-942B-43909C498951

Prog ID EnterpriseVault.RetentionCategory

Page 410: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

410 Retention APIIRetentionCategory :: Period

IRetentionCategory :: PeriodThis property describes the number of retention units (days, weeks, months, years) an item is to be retained.

The property is read/write.

SyntaxHRESULT Period([out, retval] long* pVal);HRESULT Period([in] long newVal);

Parameters

RemarksIf the value of Period is 999999, and the value of Units is Years, the retention period is “for ever”.

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass();

[out, retval] long* pVal Reference to the number of retention units (days, weeks, months, years) an item is to be retained.

[in] long newVal The range of permitted values is from 1 to 999999 inclusive.

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range (1 - 999999)

Page 411: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

411Retention APIIRetentionCategory :: Period

retcat.Name = “Finance”;retcat.Description = “For finance depts”;retcat.Identifier = “xyz”;retcat.Units = RetentionUnits.Months;retcat.Period = 10;retcat.IsVisible = true;retcat.OnHold = true;retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

string name = retCat.Name;string descr = retCat.Description;string ident = retCat.Identifier;RetentionUnits ru = retCat.Units;long period = retCat.Period;bool isVis = retCat.IsVisible;bool onHold = retCat.OnHold;bool locked = retCat. Locked;

Page 412: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

412 Retention APIIRetentionCategory :: Units

IRetentionCategory :: UnitsThis property describes whether the period is expressed in days, weeks, months or years.

The property is read/write.

SyntaxHRESULT Units([out, retval] RetentionUnits* pVal);HRESULT Units([in] RetentionUnits newVal);

Parameters

RemarksIf the value of Period is 999999, and the value of Units is Years, the retention period is “for ever”.

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

[out, retval] RetentionUnits* pVal Enumerated value for type of retention units (days, weeks, months, years).

See “Retention Units enumeration” on page 389.

[in] RetentionUnits newVal RetentionUnits enumerated value.

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range (1 - 999999)

Page 413: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

413Retention APIIRetentionCategory :: Units

IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass();

retcat.Name = “Finance”;retcat.Description = “For finance depts”;retcat.Identifier = “xyz”;retcat.Units = RetentionUnits.Months;retcat.Period = 10;retcat.IsVisible = true;retcat.OnHold = true;retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

string name = retCat.Name;string descr = retCat.Description;string ident = retCat.Identifier;RetentionUnits ru = retCat.Units;long period = retCat.Period;bool isVis = retCat.IsVisible;bool onHold = retCat.OnHold;bool locked = retCat. Locked;

Page 414: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

414 Retention APIIRetentionCategory :: IsVisible

IRetentionCategory :: IsVisibleThis property describes whether the retention category is to be displayed to end users.

The property is read/write.

SyntaxHRESULT IsVisible([out, retval] VARIANT_BOOL* pVal);HRESULT IsVisible([in] VARIANT_BOOL newVal);

Parameters

RemarksAll retention categories are visible to administrators in the Administration Console, even if this the value of this property is FALSE.

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass();

retcat.Name = “Finance”;

[out, retval] VARIANT_BOOL* pVal Reference to current value.

[in] VARIANT_BOOL newVal New value.

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range (1 - 999999)

Page 415: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

415Retention APIIRetentionCategory :: IsVisible

retcat.Description = “For finance depts”;retcat.Identifier = “xyz”;retcat.Units = RetentionUnits.Months;retcat.Period = 10;retcat.IsVisible = true;retcat.OnHold = true;retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

string name = retCat.Name;string descr = retCat.Description;string ident = retCat.Identifier;RetentionUnits ru = retCat.Units;long period = retCat.Period;bool isVis = retCat.IsVisible;bool onHold = retCat.OnHold;bool locked = retCat. Locked;

Page 416: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

416 Retention APIIRetentionCategory :: Identifier

IRetentionCategory :: IdentifierThis parameter uniquely identifies the retention category.

The property is read/write.

SyntaxHRESULT Identifier([out, retval] BSTR* pVal);HRESULT Identifier([in] BSTR newVal);

Parameters

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass();

retcat.Name = “Finance”;retcat.Description = “For finance depts”;retcat.Identifier = “xyz”;retcat.Units = RetentionUnits.Months;retcat.Period = 10;retcat.IsVisible = true;retcat.OnHold = true;retcat.Locked = true;

retCats.Add(retCat);

[out, retval] BSTR* pVal Pointer to a string containing the retention category Id.

[in] BSTR newVal String containing retention category Id (up to 250 Unicode characters).

S_OK Success.

E_POINTER pVal is an invalid pointer.

Page 417: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

417Retention APIIRetentionCategory :: Identifier

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

string name = retCat.Name;string descr = retCat.Description;string ident = retCat.Identifier;RetentionUnits ru = retCat.Units;long period = retCat.Period;bool isVis = retCat.IsVisible;bool onHold = retCat.OnHold;bool locked = retCat. Locked;

Page 418: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

418 Retention APIIRetentionCategory :: Name

IRetentionCategory :: NameThis parameter identifies the retention category to end users and the administrator.

The property is read/write.

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

Parameters

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass();

retcat.Name = “Finance”;retcat.Description = “For finance depts”;retcat.Identifier = “xyz”;retcat.Units = RetentionUnits.Months;retcat.Period = 10;retcat.IsVisible = true;retcat.OnHold = true;retcat.Locked = true;

[out, retval] BSTR* pVal The current retention category name.

[in] BSTR newVal New retention category name.

Maximum length is 32 unicode characters.

S_OK Success.

E_POINTER pVal is an invalid pointer.

Page 419: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

419Retention APIIRetentionCategory :: Name

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

string name = retCat.Name;string descr = retCat.Description;string ident = retCat.Identifier;RetentionUnits ru = retCat.Units;long period = retCat.Period;bool isVis = retCat.IsVisible;bool onHold = retCat.OnHold;bool locked = retCat. Locked;

Page 420: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

420 Retention APIIRetentionCategory :: Description

IRetentionCategory :: DescriptionThis property describes the retention category to the administrator.

The property is read/write.

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

Parameters

RemarksWhen creating a retention category, this property must be set. The value cannot be an empty string.

Return value

[out, retval] BSTR* pVal Pointer to description of retention category.

[in] BSTR newVal New description of retention category.

Maximum length is 127 unicode characters.

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is either an empty string or is greater than 127 characters in length.

Page 421: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

421Retention APIIRetentionCategory :: OnHold

IRetentionCategory :: OnHoldThis property describes whether archived items with a particular retention category can be deleted or expired. This protection applies during the retention period, and also after the retention period has expired.

While this property remains true, neither users nor Enterprise Vault storage expiry can delete items that have been stored using this retention category.

The property is read/write.

SyntaxHRESULT OnHold([out, retval] VARIANT_BOOL* pVal);HRESULT OnHold([in] VARIANT_BOOL newVal);

Parameters

RemarksThis retention category hold is different from the Legal Hold feature described in “About Legal Hold” on page 313.

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass();

[out, retval] VARIANT_BOOL* pVal Pointer to a VARIANT_BOOL containing the current value.

[in] VARIANT_BOOL newVal New value.

S_OK Success.

E_POINTER pVal is an invalid pointer.

Page 422: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

422 Retention APIIRetentionCategory :: OnHold

retcat.Name = “Finance”;retcat.Description = “For finance depts”;retcat.Identifier = “xyz”;retcat.Units = RetentionUnits.Months;retcat.Period = 10;retcat.IsVisible = true;retcat.OnHold = true;retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

string name = retCat.Name;string descr = retCat.Description;string ident = retCat.Identifier;RetentionUnits ru = retCat.Units;long period = retCat.Period;bool isVis = retCat.IsVisible;bool onHold = retCat.OnHold;bool locked = retCat.Locked;

Page 423: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

423Retention APIIRetentionCategory :: Locked

IRetentionCategory :: LockedThis property enables a lock to be put on a retention category. This prevents an administrator from inadvertently modifying the retention category.

The property is read/write.

SyntaxHRESULT Locked([out, retval] VARIANT_BOOL* pVal);HRESULT Locked([in] VARIANT_BOOL newVal);

Parameters

RemarksIn the Administration Console, this lock feature can be controlled using the checkbox, Lock this Retention Category, in the retention category properties.

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

IRetentionCategory retcat = (IRetentionCategory) new RetentionCategoryClass();

retcat.Name = “Finance”;retcat.Description = “For finance depts”;retcat.Identifier = “xyz”;retcat.Units = RetentionUnits.Months;

[out, retval] VARIANT_BOOL* pVal Pointer to current value.

[in] VARIANT_BOOL newVal New value.

S_OK Success.

E_POINTER pVal is an invalid pointer.

Page 424: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

424 Retention APIIRetentionCategory :: Locked

retcat.Period = 10;retcat.IsVisible = true;retcat.OnHold = true;retcat.Locked = true;

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory retCat = (IRetentionCategory)retcats.Item(i + 1);

string name = retCat.Name;string descr = retCat.Description;string ident = retCat.Identifier;RetentionUnits ru = retCat.Units;long period = retCat.Period;bool isVis = retCat.IsVisible;bool onHold = retCat.OnHold;bool locked = retCat.Locked;

Page 425: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

425Retention APIIRetentionCategory2 :: ExpiryBasis

IRetentionCategory2 :: ExpiryBasisThis property indicates the date from which storage expiry is calculated.

The property is read/write.

SyntaxHRESULT ExpiryBasis([out, retval] RetentionDateBasis* pVal);HRESULT ExpiryBasis([in] RetentionDateBasis newVal);

Parameters

RemarksTo retrieve the value of this property use the Get method; it is not returned by the Lookup method.

Return value

Example[in]

IRetentionCategories retcats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

[out, retval] RetentionDateBasis* pVal Enumeration value for date used to calculate storage expiry.

See “Retention Date Basis enumeration” on page 389.

[in] RetentionDateBasis newVal RetentionDateBasis enumeration value.

S_OK Success.

E_POINTER pVal is an invalid pointer.

E_INVALIDARG newVal is outside the bounds of the permitted range.

Page 426: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

426 Retention APIIRetentionCategory2 :: ExpiryBasis

IRetentionCategory2 retcat2 = (IRetentionCategory2) new RetentionCategoryClass();

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

retCats.Add(retCat);

[out]

IRetentionCategories retCats = (IRetentionCategories) new RetentionCategoriesClass();

retCats.DirectoryDNSAlias = “SERVER1”;

for (int i = 0; i < retCats.Count; i++){

IRetentionCategory2 retCat = (IRetentionCategory2)retcats.Item(i + 1);

string name = retCat2.Name;string descr = retCat2.Description;

string ident = retCat2.Identifier;RetentionUnits ru = retCat2.Units;long period = retCat2.Period;bool isVis = retCat2.IsVisible;

bool onHold = retCat2.OnHold;bool locked = retCat2.Locked;RetentionDataBasis rdb = retCat2.ExpiryBasis;

Page 427: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

7

Filtering APIs

This chapter describes the following APIs available for adding proprietary external filters to Enterprise Vault archiving tasks:

■ Exchange Filtering API

■ Domino Filtering API

About the Filtering APIsFiltering involves selecting specific items according to set criteria, and performing certain actions on those items. Items may be selected using attributes such as author, message recipients, subject, or a combination of attributes. Actions could include, for example, archiving the item with a specific retention category, or storing the item in a particular archive. Other actions could include deleting the item, or removing attachments.

Enterprise Vault includes generic filters for Exchange Server archiving and Domino Server archiving. To use these generic filters, you do not require access to the Enterprise Vault API. For an overview of filtering, and instructions on how to configure the generic Enterprise Vault filters, see the Configuring custom filtering section in the following manuals:

Setting Up Exchange Server Archiving

Setting Up Domino Server Archiving

The Enterprise Vault Filtering APIs provide a "plug-in" interface that enables you to develop proprietary filters that perform a wider range of tasks than is possible using the generic filters. For example, you may want to collect statistics on particular item types, classify items based on metadata or content, or add proprietary information to items as they are archived.

The Exchange Filtering API, is presented as a set of COM interfaces. This API can be used to develop proprietary filters for the following archiving tasks:

■ Exchange Mailbox task

Page 428: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

428 Filtering APIsAbout the Filtering APIs

■ Exchange Journaling task

■ Exchange Public Folder task

The Domino Filtering API, is presented as a set of .NET interfaces. This API can be used to develop proprietary filters for the Domino Journaling task.

You can configure multiple filters for a particular type of archiving; the associated archiving task will process these in order.

You enable filtering by configuring registry settings for the associated archiving task.

The following points summarize the steps you need to take to configure filtering:

■ Develop your filter class using the API interfaces described in this chapter. In the filter you can use the Content Management DiagnosticsAPI class to add tracing and event logging.

See “DiagnosticsAPI object” on page 364

■ Configure the appropriate filtering registry settings for the archiving tasks that you want to perform filtering. The registry settings enable filtering for the archiving task and define the external filters to process.

Details of the registry settings are given in the following sections:

“Exchange filtering registry settings” on page 430

“Domino filtering registry settings” on page 474

■ Restart the associated archiving tasks.

Details of the filtering APIs are given in the following sections:

■ “Exchange Filtering API” on page 429

■ “Domino Filtering API” on page 473

Page 429: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

429Filtering APIsExchange Filtering API

Exchange Filtering APIThe Exchange Filtering API provides a mechanism for COM components to be loaded by the appropriate Exchange archiving task, and called on a per-message basis during the archiving process.

Figure 7-1 Overview of Exchange filtering

The figure, “Overview of Exchange filtering”, illustrates how Enterprise Vault implements Exchange external filters:

■ If the registry settings are configured to enable filtering for the Exchange Mailbox, Journaling or Public Folder tasks, the task calls the task filter controller when processing a message.

■ The task filter controller invokes the first external filter, which implements the IExternalFilter interface.

■ The external filter calls the IArchivingControl3 interface, which is implemented by the task filter controller, to retrieve information about the message.

Page 430: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

430 Filtering APIsExchange Filtering API

■ The filter processes the message synchronously, using the methods and properties of the IArchivingControl3 interface to set properties that define how the Exchange archiving task is to process the message.

■ Provided the stopFiltering parameter is not set to TRUE, each filter is applied in turn to the message.

■ After the message has been processed by all of the registered filters, the task filter controller then invokes the FilteringComplete method for each filter. This enables the filter to tidy up and release any resources used while processing the message.

■ The Exchange archiving task then completes archiving the message, as modified by the external filters and also taking account of any archiving actions set by the external filters.

Developing Exchange external filters

Note: External filters for Exchange filtering must be developed in unmanaged code. This is because the Enterprise Vault Exchange archiving tasks are written in an unmanaged language and Microsoft has not implemented a managed (.NET) MAPI library.

A filter should be implemented as an apartment-threaded, in-process COM server that references the following libraries:

■ Enterprise Vault External Filtering Type Library

■ Enterprise Vault Archiving Control Type Library

To develop a filter for Exchange filtering, you need to obtain and install the appropriate Enterprise Vault archiving license.

Exchange filtering registry settingsFiltering for Enterprise Vault Exchange Mailbox, Journaling, and Public Folder tasks is enabled using registry settings under the following registry key:HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\External Filtering

You add a new key to specify the type of archiving task that is to perform the filtering. The key can be one of the following:

■ Mailbox

■ Journaling

Page 431: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

431Filtering APIsExchange Filtering API

■ PublicFolder

For example, to add filtering for the Exchange Mailbox archiving tasks, you add the Mailbox key:HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\External Filtering\Mailbox

You then add a string value to the Mailbox key for each of the required external filters. For the name of each filter entry, use the values, 1, 2, 3 and so on. If there are multiple filters, the filter names should form an unbroken numerical sequence. The filters are applied in numerical order. If one number is missing, no further filters are applied.

Note: When configuring filtering for Exchange journaling tasks, if the Compliance Accelerator Journaling Connector filter exists, it must be last in the sequence.

For the value of each filter entry give the ProgID (that is, the ProjectName.ClassName of the COM class implementing IExternalFilter for this particular filter). For example, the value for the generic Enterprise Vault filter for Exchange Server filtering is EnterpriseVault.CustomFilter.

The following example shows three external filters that have been configured for the Exchange Mailbox archiving tasks. HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\External Filtering\Mailbox 1 = ACompany.Filter12 = ACompany.Filter24 = ACompany.Filter3

In this case, filter 1 is applied and then filter 2. However, filter processing stops after filter 2 because the filter name sequence is broken.

The following optional DWORD values can also be created to control filtering:

■ Override — This setting has the following effect:

■ Exchange Journaling tasks. If created under the Journaling key, and given the value, 1, this setting forces the Exchange Journaling tasks to retry messages that were marked as MARK_DO_NOT_ARCHIVE by a previous filter.

Page 432: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

432 Filtering APIsExchange Filtering API

If the value is 0, or the setting does not exist, the Exchange Journaling tasks do not retry messages that are marked as MARK_DO_NOT_ARCHIVE.

■ Exchange Mailbox and Public Folder tasks. If created under the Maibox or PublicFolder keys, and given the value, 1, this setting turns off custom filtering.

If the value is 0, or the setting does not exist, the archiving tasks implement the configured custom filters.

■ MoveOnFilterFailure — This can be set for Exchange Journaling tasks or Exchange Mailbox tasks. If this setting has the value 1, and an unhandled error occurs in the external filter, the message involved is moved to the folder, Failed external filter. This folder is created automatically if it does not exist.

If the value is 0, or the setting does not exist, the archiving tasks take the following action:

■ Exchange Journaling task. When an unhandled error occurs in the external filter, the task moves the associated messages to the folder,Enterprise Vault Journaling Service\Invalid Journal Report in the journal mailbox.

■ Exchange Mailbox task. When an unhandled error occurs in the external filter, the archiving task does not move the associated messages. The task tries to process the messages during each archiving run

In the following example, the Override and MoveOnFilterFailure settings have been created under the Mailbox registry key:HKEY_LOCAL_MACHINE \SOFTWARE \KVS \Enterprise Vault \External Filtering \Mailbox 1 = ACompany.Filter1 2 = ACompany.Filter2 Override = 0 MoveOnFilterFailure = 1

If you make changes to the custom filtering registry settings, restart the associated archiving tasks to implement the changes.

For further details of the filtering registry settings, see the Configuring custom filtering chapter in the the manual, Setting Up Exchange Server Archiving.

Page 433: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

433Filtering APIsEnumerations (Exchange filtering)

Enumerations (Exchange filtering)This section lists the enumerations for the Exchange Filtering API.

EV_ACTION enumerationThe 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 enumerationThe following enumeration values are defined for EV_ATTACHMENT_ACTION:enum EV_ATTACHMENT_ACTION{

NO_ATTACHMENT_ACTION = 0, DELETE_ATTACHMENT = 1,REPLACE_ATTACHMENT = 2

};

If the attachment action is to replace attachments, users will see a file called Deleted Attachments.txt attached to messages that have had attachments deleted by the filter. When they open this file, it contains a list of the names of files that have been deleted.

The contents of this file are taken from the file, CF_Replace_Attachment.txt, in the Enterprise Vault program folder (typically, C:\Program Files\Enterprise Vault). If required, you can modify the text of this file. For example, you may want to localize the descriptive text.

EV_RETRY_STATUS enumerationThe 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

Page 434: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

434 Filtering APIsEnumerations (Exchange filtering)

};

UNKNOWN_IF_RETRY does not indicate an error; it indicates that the task could not determine if the status was a retry. For example, this may be returned if the archiving task does not support detecting retries. Filters should interpret an UNKNOWN_IF_RETRY status as IS_NOT_RETRY.

EV_REARCHIVE_STATUS enumerationThe following enumeration values are defined for EV_REARCHIVE_STATUS:enum EV_REARCHIVE_STATUS{

UNKNOWN_IF_REARCHIVE = 0, IS_NOT_REARCHIVE = 1,IS_A_REARCHIVE = 2

};

UNKNOWN_IF_REARCHIVE does not indicate an error; it indicates that the task could not determine if the status was a re-archive. For example, this may be returned if the archiving task does not support detecting re-archives. Filters should interpret an UNKNOWN_IF_REARCHIVE status as IS_NOT_REARCHIVE.

Message direction enumerationThe 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

}

Page 435: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

435Filtering APIsIExternalFilter interface

IExternalFilter interfaceAn external filter implements the following interface:

■ IExternalFilter

Syntaxinterface IExternalFilter : IDispatch

Member summary

RemarksThe external filter must implement the COM interface, IExternalFilter, which is called by the task filter controller.

All methods must be implemented, even if they return only S_OK.

If the filter makes changes to the message, and the changes are to be reflected in the Exchange Server store or the Enterprise Vault archive or both, then call the IArchivingControl2 :: MAPISaveChanges method at the end of the method (ProcessFilter or FilteringComplete) that made the changes to the message. Making a change to the message in ProcessFilter and delaying the MAPISaveChanges call to FilteringComplete is not regarded as good practice.

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.

Page 436: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

436 Filtering APIsIExternalFilter :: Initialize

IExternalFilter :: InitializeThis method is called during Exchange archiving task initialization.

SyntaxHRESULT Initialize([in] IDispatch *pArchivingControl);

Parameters

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

[in] IDispatch *pArchivingControl Reference to the IArchvingControl interface.

Page 437: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

437Filtering APIsIExternalFilter :: ProcessFilter

IExternalFilter :: ProcessFilterThis method is called per-message during the archiving process. The ProcessFilter method is where you process the message to your requirements.

SyntaxHRESULT ProcessFilter([out, retval] VARIANT_BOOL *bStopFiltering);

Parameters

RemarksTo get a reference to the message, use the IArchivingControl :: MAPIMessage property.

To find or change the current action to be taken on the message, use the IArchivingControl :: Action property.

Similarly to change the retention category or archive for the item, use the currentRetentionCategoryId and currentVaultId properties on the IArchivingControl interface.

The external filter must be written to handle concurrent calls. If the filter accesses a shared resource, it must use appropriate concurrency protection.

See also■ “IArchivingControl :: MAPIMessage” on page 450.

■ “IArchivingControl :: Action” on page 448.

■ “IArchivingControl :: currentVaultId” on page 443.

■ “IArchivingControl :: currentRetentionCategoryId” on page 444.

[out, retval] VARIANT_BOOL *bStopFiltering Value of true stops the filter controller from processing any more filters on the current item.

Page 438: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

438 Filtering APIsIExternalFilter :: FilteringComplete

IExternalFilter :: FilteringCompleteThis 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.

SyntaxHRESULT FilteringComplete();

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

Page 439: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

439Filtering APIsIArchivingControl interface for Exchange filtering

IArchivingControl interface for Exchange filteringThe task filter controller implements the following interfaces:

■ IArchivingControl

■ IArchivingControl2

■ IArchivingControl3

The IArchivingControl interface enables an external filter to retrieve and modify properties on the current message.

The IArchivingControl2 interface extends the IArchivingControl interface and adds methods and properties to provide the following functionality:

■ Improved handling of MAPI Message Classes.

■ Ability to open an archived item from a URL.

■ Method for persisting changes made to messages by external filters, so that the changes are reflected in the Exchange Server store and the Enterprise Vault archive.

The IArchivingControl3 interface extends the IArchivingControl2 interface and adds properties to retrieve sender and recipient information as XML.

Syntaxinterface IArchivingControl3 : IArchivingControl2 :

IArchivingControl : IDispatch

Member summary

Table 7-1 IArchivingControl properties

Property Read/Write Description

currentVaultId Read/Write The Id of the archive associated with the current item.

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

defaultRetentionCategoryId Read only The Id of the default retention category for the Enterprise Vault Site.

deleteOriginalItem Read/Write Whether the item is to be deleted from the original location after it has been archived.

Page 440: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

440 Filtering APIsIArchivingControl interface for Exchange filtering

createShortcutToItem Read/Write Whether a shortcut is created in the original location after the item has been archived.

Action Read/Write The action to be taken by the archiving task when the filtering process is complete.

MAPISession Read only Gets a MAPI session.

MAPIMessage Read only A pointer to the current MAPI message.

IndexedPropertiesSet Read only Lists the properties that have been added using AddIndexedProperty.

TransactionID Read only Identifies archiving action.

AgentType Read only Identifies the type of archiving task using the filter.

AgentAssignedRetentionCategoryId Read only Identifies the original retention category assigned.

AgentAssignedVaultId Read only Identifies the original destination archive.

AttachmentAction Read/Write Defines action to be taken when processing message attachments.

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

ReArchiveStatus Read only Indicates if current archiving action is rearchiving an item that has been restored from the archive.

Table 7-1 IArchivingControl properties

Property Read/Write Description

Page 441: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

441Filtering APIsIArchivingControl interface for Exchange filtering

Table 7-2 IArchivingControl2 properties

Property Read/Write Description

BrowserViewURL Read only Provides a URL that can be used to present an HTML view of the original item.

NativeItemURL Read only Provides a URL that can be use to fetch the original item.

MessageClass Read only Identifies the original value of the MAPI Message Class property.

Table 7-3 IArchivingControl methods

Method Description

AddIndexedProperty Adds metadata to the item. The metadata will be indexed.

AddIndexPropertyToSet Adds custom properties to a named custom property set.

AddIndexPropertySet Adds a named custom property set.

GetFilterProperty Retrieves value of variable set using PutFilterProperty by another filter.

PutFilterProperty Sets a variable that can be queried by other filters.

Table 7-4 IArchivingControl2 method

Method Description

MAPISaveChanges Enables changes to the current message to be saved.

Page 442: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

442 Filtering APIsIArchivingControl interface for Exchange filtering

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.

Table 7-5 IArchivingControl3 properties

Method Description

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

EnvelopeSenderRecipientXML Retrieves an XML document containing the sender and recipient information taken from the envelope message.

MessageDirection Indicates the direction in whish the message was travelling (in relation to the domain defined as internal).

Page 443: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

443Filtering APIsIArchivingControl :: currentVaultId

IArchivingControl :: currentVaultIdThe Id of the archive associated with the current item.

This property is read/write.

SyntaxHRESULT currentVaultId([in] BSTR newVal);HRESULT currentVaultId([out, retval] BSTR *pVal);

Parameters

RemarksThe 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

[in] BSTR newVal Id of archive to be assigned.

[out, retval] BSTR *pVal Id of archive assigned.

Page 444: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

444 Filtering APIsIArchivingControl :: currentRetentionCategoryId

IArchivingControl :: currentRetentionCategoryIdThe Enterprise Vault retention category to be assigned to the current item.

This property is read/write.

SyntaxHRESULT currentRetentionCategoryId([in] BSTR newVal);HRESULT currentRetentionCategoryId([out, retval] BSTR *pVal);

Parameters

RemarksThe currentRetentionCategoryId property enables the external filter to get and set the retention category that is to be applied to the item when it is stored. The value originally assigned can be retrieved using the AgentAssignedRetentionCategoryId property.

An example value is:18306BF113C2C444096279660836252821b10000EVArchiveSite1

Use the Retention API to retrieve details of retention categories, and create new retention categories.

See “Retention API” on page 387.

[in] BSTR newVal New retention category Id.

[out, retval] BSTR *pVal Retention category Id.

Page 445: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

445Filtering APIsIArchivingControl :: defaultRetentionCategoryId

IArchivingControl :: defaultRetentionCategoryIdThe default retention category for the Enterprise Vault Site.

This property is read only.

SyntaxHRESULT defaultRetentionCategoryId([out, retval] BSTR *pVal);

Parameters

RemarksThe defaultRetentionCategoryId property enables the external filter to get the default retention category for the Enterprise Vault Site.

[out, retval] BSTR *pVal Id of default retention category for site.

Page 446: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

446 Filtering APIsIArchivingControl :: deleteOriginalItem

IArchivingControl :: deleteOriginalItemThis property indicates whether the item is to be deleted from the original location after it has been archived.

This property is read/write.

SyntaxHRESULT deleteOriginalItem([in] BOOL newVal);HRESULT deleteOriginalItem([out, retval] BOOL *pVal);

Parameters

RemarksWhen the archiving task is running in report mode, the action is ignored.

[in] BOOL newVal New value.

[out, retval] BOOL *pVal Pointer to current value.

Page 447: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

447Filtering APIsIArchivingControl :: createShortcutToItem

IArchivingControl :: createShortcutToItemThis property indicates whether a shortcut is created in the original location after the item has been archived.

This property is read/write.

SyntaxHRESULT createShortcutToItem([in] BOOL newVal);HRESULT createShortcutToItem([out, retval] BOOL *pVal);

Parameters

RemarksWhen the task is running in report mode the action is ignored.

[in] BOOL newVal New value.

[out, retval] BOOL *pVal Pointer to current value.

Page 448: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

448 Filtering APIsIArchivingControl :: Action

IArchivingControl :: ActionThis property indicates the action to be taken by the archiving task when the filtering process is complete.

This property is read/write.

SyntaxHRESULT Action([in] EV_ACTION newVal);HRESULT Action([out, retval] EV_ACTION *pVal);

Parameters

RemarksFor EV_ACTION enumeration values, see “EV_ACTION enumeration” on page 433.

The default action is to archive the item (ARCHIVE_ITEM enumeration value).

[in] EV_ACTION newVal EV_ACTION enumeration value.

[out, retval] EV_ACTION *pVal Current EV_ACTION enumeration value.

Page 449: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

449Filtering APIsIArchivingControl :: MAPISession

IArchivingControl :: MAPISession This property returns a MAPI session for the current message.

This property is read only.

SyntaxHRESULT MAPISession([out, retval] IUnknown **pUnkVal);

Parameters

[out, retval] IUnknown **pUnkVal Pointer to MAPI session.

Page 450: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

450 Filtering APIsIArchivingControl :: MAPIMessage

IArchivingControl :: MAPIMessageThis property provides a pointer to the current MAPI message (P2).

This property is read only.

SyntaxHRESULT MAPIMessage([out, retval] IUnknown **pUnkVal);

Parameters

RemarksThe properties of the message can be accessed and updated using standard MAPI calls. Any changes should be persisted using MAPISaveChanges at the end of the method (ProcessFilter or FilteringComplete) that made the changes to the message.

As MAPISaveChanges does not save changes made to attachments of P2 messages, these will have to be saved first by the caller.

See also■ “IArchivingControl2 :: MAPISaveChanges” on page 467.

[out, retval] IUnknown **pUnkVal Pointer to MAPI message.

Page 451: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

451Filtering APIsIArchivingControl :: AddIndexedProperty

IArchivingControl :: AddIndexedPropertyThis method enables you to add a property to the custom index metadata for the item.

SyntaxHRESULT AddIndexedProperty([in] BSTR propname,

[in] BSTR value);

Parameters

RemarksUsing this method adds the property to the default property set.

Properties added using this method are always searchable and retrievable.

To avoid property name clashes, you are recommended to use AddIndexPropertyToSet to add the property to a named property set. This will also enable you to control whether the property is searchable and retrievable.

[in] BSTR propname Property name.

[in] BSTR value Property value.

Page 452: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

452 Filtering APIsIArchivingControl :: IndexedPropertiesSet

IArchivingControl :: IndexedPropertiesSetThis property lists the properties that have been added to the custom index metadata of the item using AddIndexedProperty.

The property is read only.

SyntaxHRESULT IndexedPropertiesSet([out, retval] BSTR *pVal);

Parameters

RemarksThis property enables the filter to find out the custom index metadata that has been added to the item using AddIndexedProperty method.

The properties are returned as XML which can be loaded into an ISimpleIndexMetadata object using the FromXML method.

See “ISimpleIndexMetadata :: FromXML” on page 290.

[out, retval] BSTR *pVal Pointer to the XML list of properties.

Page 453: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

453Filtering APIsIArchivingControl :: AddIndexPropertyToSet

IArchivingControl :: AddIndexPropertyToSetThis method adds a custom index metadata property to a named property set.

SyntaxHRESULT AddIndexPropertyToSet([in] BSTR setname,

[in] BSTR propname, [in] BSTR propvalue);

Parameters

RemarksThe searchable and retrievable settings for the property set will define how the property is handled.

If the property set exists, the property will be added to that property set. If it does not exist, the property set will be created first.

If a property set is created "by default", it will have the default attributes of searchable ="true" and retrievable ="false".

If a property needs to be retrievable, the property set needs to be created using the AddIndexPropertySet method, where the values for searchable and retrievable can be set explicitly.

Properties can be multi-valued. When adding a property, the existence of that property within the specified set is checked and, if present, the value is added as an element of that property.

[in] BSTR setname Name of property set.

[in] BSTR propname Name of property.

[in] BSTR propvalue Value of property.

Page 454: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

454 Filtering APIsIArchivingControl :: AddIndexPropertySet

IArchivingControl :: AddIndexPropertySetThis method adds a named custom property set. Custom index metadata properties can be added to this set using AddIndexPropertyToSet method.

SyntaxHRESULT AddIndexPropertySet([in] BSTR setname,

[in] BOOL searchable, [in] BOOL retrievable);

Parameters

RemarksProperties added can be grouped in named property sets. It is good practice to use a named property sets in order to avoid name clashes with other filter additions. The property set names, Vault, EnterpriseVault, KVS, Veritas, and Symantec are reserved.

Properties defined as Searchable will be indexed and can be searched for using the Search API. Properties defined as Retrievable can be retrieved and displayed later with the item. Each property set can be marked as Searchable or Retrievable or both.

See “SimpleIndexMetadata object” on page 277.

Property sets do not need to be created before properties are added to them.

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

Page 455: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

455Filtering APIsIArchivingControl :: TransactionID

IArchivingControl :: TransactionIDThis property is the unique identifier that will be assigned to the archived item.

The property is read only.

SyntaxHRESULT TransactionID([out, retval] BSTR* pTransactionID);

Parameters

RemarksThis property can be used as the IItem :: Id value in the Content Management API to subsequently fetch the archived item.

See also ■ “IArchivingControl :: RetryStatus” on page 462.

■ “IArchivingControl :: ReArchiveStatus” on page 463.

[out, retval] BSTR* pTransactionID Transaction Id.

Page 456: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

456 Filtering APIsIArchivingControl :: AgentType

IArchivingControl :: AgentTypeThis property identifies the type of the current archiving task.

The property is read only.

SyntaxHRESULT AgentType([out, retval] BSTR* pVal);

Parameters

RemarksThe value can be one of the following:

■ Mailbox

■ Journaling

■ PublicFolder

[out, retval] BSTR* pVal Current archiving task type.

Page 457: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

457Filtering APIsIArchivingControl :: AgentAssignedRetentionCategoryId

IArchivingControl :: AgentAssignedRetentionCategoryId

This property identifies the original retention category assigned, in case other filters have assigned a different retention category.

The property is read only.

SyntaxHRESULT AgentAssignedRetentionCategoryId([out, retval] BSTR* pVal);

Parameters

RemarksUse the Retention API to retrieve details of retention categories, and create new retention categories.

See “Retention API” on page 387.

[out, retval] BSTR* pVal Retention category Id.

Page 458: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

458 Filtering APIsIArchivingControl :: AgentAssignedVaultId

IArchivingControl :: AgentAssignedVaultIdThis property identifies the original destination archive, in case other filters have redirected the message to an alternative archive.

The property is read only.

SyntaxHRESULT AgentAssignedVaultId([out, retval] BSTR* pVal);

Parameters

[out, retval] BSTR* pVal Archive Id.

Page 459: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

459Filtering APIsIArchivingControl :: GetFilterProperty

IArchivingControl :: GetFilterProperty This method enables communication between filters; a filter property can be set by one filter and queried by another.

SyntaxHRESULT GetFilterProperty([in] BSTR Key); HRESULT GetFilterProperty([out, retval] BSTR *pVal);

Parameters

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

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

Page 460: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

460 Filtering APIsIArchivingControl :: PutFilterProperty

IArchivingControl :: PutFilterPropertyThis method is used to set a filter property that is passed on to subsequent filters.

SyntaxHRESULT PutFilterProperty ([in] BSTR Key,

[in] BSTR Setting);

Parameters

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

[in] BSTR Key Key for filter property.

[in] BSTR Setting Value of filter property.

Page 461: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

461Filtering APIsIArchivingControl :: AttachmentAction

IArchivingControl :: AttachmentActionThis property defines the action to be taken when processing attachments to messages.

This property is read/write.

SyntaxHRESULT AttachmentAction([in] EV_ATTACHMENT_ACTION newVal);HRESULT AttachmentAction([out, retval] EV_ATTACHMENT_ACTION *pVal);

Parameters

RemarksThis property is not currently supported.

With Exchange server filtering, if the message attributes satisfy a rule, any attachments are then evaluated using attachment attributes. When an attachment matches a rule, the action specified by ATTACHMENT_ACTION is applied to the attachment.

For EV_ATTACHMENT_ACTION enumeration values, see “EV_ATTACHMENT_ACTION enumeration” on page 433.

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

Page 462: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

462 Filtering APIsIArchivingControl :: RetryStatus

IArchivingControl :: RetryStatusThis property enables the caller to determine if the current attempt to archive an item is a retry.

The property is read only.

SyntaxHRESULT RetryStatus([out, retval] EV_RETRY_STATUS* pRetryStatus

Parameters

RemarksSometimes when an item fails to be archived, the item will be subsequently retried by the archiving task. In this case, the item will also be refiltered.

If this is a retry, the transactionID will typically be the same as the previous attempt.

This property can be used to avoid the following when processing retries:

■ Counting the same transaction multiple times.

■ Storing the same transaction (for example, in a database) multiple times.

For EV_RETRY_STATUS enumeration values, see “EV_RETRY_STATUS enumeration” on page 433.

See also■ “IArchivingControl :: TransactionID” on page 455.

■ “IArchivingControl :: ReArchiveStatus” on page 463.

[out, retval] EV_RETRY_STATUS* pRetryStatus Pointer to an EV_RETRY_STATUS type containing the current value.

Page 463: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

463Filtering APIsIArchivingControl :: ReArchiveStatus

IArchivingControl :: ReArchiveStatusIf 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.

SyntaxHRESULT ReArchiveStatus([out, retval] EV_REARCHIVE_STATUS*

pReArchiveStatus);

Parameters

RemarksIf this is a rearchive, the transactionID will typically be the same as the previous archive transaction.

This property can be used to avoid the following when processing rearchive transactions:

■ Counting the same transaction multiple times.

■ Storing the same transaction (for example, in a database) multiple times.

For EV_REARCHIVE_STATUS enumeration values, see “EV_REARCHIVE_STATUS enumeration” on page 434.

[out, retval] EV_REARCHIVE_STATUS* pReArchiveStatus Pointer to an EV_REARCHIVE_STATUS type containing the current value.

Page 464: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

464 Filtering APIsIArchivingControl2 :: BrowserViewURL

IArchivingControl2 :: BrowserViewURLThis 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.

SyntaxHRESULT BrowserViewURL([out,retval] BSTR* pVal)

Parameters

RemarksThis property will return an error if the archive Id and the saveset Id have not been set previously.

The URL returned includes the IIS virtual directory for the Enterprise Vault Web access application, but not a specific Web server name. Enterprise Vault dynamically generates the full URL as needed, with the appropriate server name for each caller.

This form of URL is compatible with Enterprise Vault Building Blocks architec-ture.

Return value

ExampleThe following is an example value of BrowserViewURL:http://webserver1.EXAMPLE.COM/EnterpriseVault/viewmessage.asp?VaultID=12B72E5122E1D714893C625CEF3A762311110000sv1.example.com&SavesetID=430D7CD1EA644810ADF10D71CF39063&Format=WEB

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

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.

Page 465: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

465Filtering APIsIArchivingControl2 :: NativeItemURL

IArchivingControl2 :: NativeItemURLThe 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.

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

Parameters

Remarks There will be an error if either the item Id or the archive Id have not been set before using this property.

The URL returned includes the IIS virtual directory for the Enterprise Vault Web access application, but not a specific Web server name. Enterprise Vault dynamically generates the full URL as needed, with the appropriate server name for each caller.

This form of URL is compatible with Enterprise Vault Building Blocks architec-ture.

Return Value

ExampleThe following is an example value of NativeItemURL:http://webserver1.EXAMPLE.COM/EnterpriseVault/download.asp?VaultID=12B72E5122E1D714893C625CEF3A762311110000sv1.example.com&SavesetID=430D7CD1EA644810ADF10D71CF39063&Request=NativeItem

[out, retval] BSTR* pVal A pointer to a BSTR that will contain the current 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.

Page 466: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

466 Filtering APIsIArchivingControl2 :: MessageClass

IArchivingControl2 :: MessageClassThis property returns the MAPI Message Class for the current item.

This property is read only.

SyntaxHRESULT MessageClass([out, retval] BSTR *pVal);

Parameters

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

ExampleAn example of a MAPI Message Class is:

IPM.Note

[out, retval] BSTR *pVal Pointer to a string containing the MAPI message class.

Page 467: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

467Filtering APIsIArchivingControl2 :: MAPISaveChanges

IArchivingControl2 :: MAPISaveChangesThis method persists changes to the current message.

SyntaxHRESULT MAPISaveChanges();

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

Page 468: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

468 Filtering APIsIArchivingControl3 :: SenderRecipientXML

IArchivingControl3 :: SenderRecipientXMLThis property retrieves an XML document containing the sender and recipient information for the current message.

The property is read only.

SyntaxHRESULT SenderRecipientXML([out, retval] IUnknown **ppStream);

RemarksFor Exchange Journaling tasks any distribution lists are expanded, regardless of the setting of the Expand distribution lists setting on the Advanced page of the Exchange Journaling policy in the Enterprise Vault Administration Console.

The property value is an XML document representing the sender and recipient information for the current message, including expanded distribution lists.

For Exchange envelope journal items this information is extracted from the P2 message and is just a representation of the sender and recipient information as taken from the MAPI message.

The return object implements IStream and can be loaded into an XMLDOMDocument. The only available IStream methods available are IStream :: CopyTo, IStream :: Read, IStream :: Seek and IStream :: Stat. All other methods return E_NOTIMPL.

Example<?xml version="1.0" encoding="UTF-16"?><ARCHIVED_ITEM xmlns:o="urn:kvsplc-com:archived_item" version="1.0"><MSG>

<RECP><TO>

<RC><DN>Display Name</DN><EA>SMTP Email Address</EA>

</RC><DL>

<DN>Distribution List Display Name</DN><EA>Distribution List SMTP Email Address</EA><TIME>2007-09-03T23:36:28</TIME><RC>

<DN>User1</DN><EA>SMTP Email Address</EA>

</RC></DL>

Page 469: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

469Filtering APIsIArchivingControl3 :: SenderRecipientXML

</TO><CC/><BCC/>

</RECP><AUTH>

<FROM><DN>Display Name</DN><EA>SMTP Email Address</EA>

</FROM></AUTH>

</MSG></ARCHIVED_ITEM>

Page 470: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

470 Filtering APIsIArchivingControl3 :: EnvelopeSenderRecipientXML

IArchivingControl3 :: EnvelopeSenderRecipientXMLThis property retrieves an XML document containing the sender and recipient information taken from the envelope message.

The property is read only.

SyntaxHRESULT EnvelopeSenderRecipientXML([out, retval] IUnknown **ppStream);

RemarksThis property is only available for Exchange envelope journal items. Any distribution lists are expanded, regardless of the setting of the Expand distribution lists setting on the Advanced page of the Exchange Journaling policy in the Enterprise Vault Administration Console.

The property value is an XML document representing the sender and recipient information for the current message, including expanded distribution lists. The recipient information as taken from the envelope report and does not contain information from the P2 message.

The return object implements IStream and can be loaded into an XMLDOMDocument. The only available IStream methods available are IStream :: CopyTo, IStream :: Read, IStream :: Seek and IStream :: Stat. All other methods return E_NOTIMPL.

Example<?xml version="1.0" encoding="UTF-16"?><ARCHIVED_ITEM xmlns:o="urn:kvsplc-com:archived_item" version="1.0"><MSG>

<RECP P1="true"><TO>

<RC><DN>Display Name</DN><EA>SMTP Email Address</EA>

</RC><DL>

<DN>Distribution List Display Name</DN><EA>Distribution List SMTP Email Address</EA><RC>

<DN>User1</DN><EA>SMTP Email Address</EA>

</RC></DL>

Page 471: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

471Filtering APIsIArchivingControl3 :: EnvelopeSenderRecipientXML

</TO><CC/><BCC>

<RC><DN>Display Name</DN><EA>SMTP Email Address</EA>

</RC></BCC><ENV>

<RC><DN>Display Name</DN><EA>SMTP Email Address</EA>

</RC></ENV>

</RECP><AUTH P1=”true”>

<FROM><DN>Display Name</DN><EA>SMTP Email Address</EA>

</FROM></AUTH>

</MSG></ARCHIVED_ITEM>

Note: EnvelopeSenderRecipientXML for Exchange 2007 envelope items will not contain any <DN> (Display Name) tags as the display name does not exist in the P1 envelope report.

Page 472: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

472 Filtering APIsIArchivingControl3 :: MessageDirection

IArchivingControl3 :: MessageDirectionThis property indicates the direction in which the message was travelling (in relation to the domain defined as internal).

SyntaxHRESULT MessageDirection([out, retval] MSG_DIRECTION *Msg_Direction);

RemarksThe property value is an enumerated value. For MSG_DIRECTION enumerated values, see “Message direction enumeration” on page 434.

This property is read only.

Page 473: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

473Filtering APIsDomino Filtering API

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

About the Domino Filtering APIThe Domino Filtering API enables you to create external filters for Domino Journaling tasks. The filters define how the Domino Journaling task selects and processes messages.

■ Messages can be selected by matching one or more attributes, such as email addresses, subject text or message direction.

■ Additional properties can be added to the Enterprise Vault index for the message.

■ The action defined for the task can be to archive the message, mark it as "do not archive", or delete it.

Marking messages reduces the overhead on the archiving task, as these messages are not re-evaluated during subsequent archiving runs, unless the Override registry setting is configured.

See “Domino filtering registry settings” on page 474

Figure 7-2 Overview of Domino filtering

The figure, “Overview of Domino filtering”, illustrates how Enterprise Vault implements Domino journal filters:

■ If the registry settings are configured to enable filtering for the Domino Journaling tasks, the Domino Journaling task calls the task filter controller when processing a message in the Domino journal database.

Page 474: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

474 Filtering APIsDomino Filtering API

■ The task filter controller invokes the first external filter, which implements the IExternalFilter interface.

■ The filter uses the methods and properties on the ILotusArchivingControl interface to retrieve information about the message.

■ The filter then processes the message. Methods and properties on the ILotusArchivingControl interface enable you to define how the Domino Journaling task is to process the message.

■ If there are several filters, each external filter is applied in turn to the message, provided the stopFiltering parameter is not set to TRUE.

■ After all the filters have been applied, the FilteringComplete method for each filter is called to perform any clean up tasks.

■ The Domino Journaling task then processes the message according to the properties set by the external filters.

Developing external filters

Note: If you plan to supply data to your external filters using XML, be aware that Microsoft does not support the use of MSXML (Microsoft’s COM-based XML parser) in .NET applications. This is described in the knowledge base article, KB 815112.

Filters developed using the Domino Filtering API must reference the .NET assembly:

■ KVS.EnterpriseVault.LotusDominoInterfaces.DLL

You can develop external filters in the programming language of your choice. For clarity, definitions are given using C#.NET syntax.

For Domino filters, if you want to use the Lotus C API for Lotus Notes/Domino to access the note, we recommend that you use managed C++. The Lotus C API for Lotus Notes/Domino is shipped with the Lotus Notes client.

To develop an external filter for Domino journaling, you need to obtain and install an Enterprise Vault Lotus Domino Journaling license.

Domino filtering registry settingsFiltering for Enterprise Vault Domino Journaling tasks is enabled using registry settings under the External Filtering key:

Page 475: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

475Filtering APIsDomino Filtering API

HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\External Filtering\Lotus Journaling

If either External Filtering or Lotus Journaling keys do not exist, then you can create them.

You create a new string entry for each filter under the Lotus Journaling key. Filter names must be an unbroken numbered sequence starting at 1.

The value of the filter name is a string value that contains the name of the .NET assembly and the relevant filter class for the new external filter:

PathToFilterAssembly!FilterClassName

For example, the value for the generic Domino filter is

KVS.EnterpriseVault.LotusDominoCustomFilter.DLL!KVS.Enterpri

seVault.LotusDomino.CustomFilter

Note that the class name is case sensitive.

If you have installed the Compliance Accelerator Journaling Connector,

KVS.EnterpriseVault.LotusDominoMsgHandler.dll!

KVS.EnterpriseVault.LotusDomino.CADominoFilter

then it must be the last in the sequence of filters. When you add other filters, you must rename the Journaling Connector to ensure that it remains last in the sequence.

Optionally, you can create a DWORD entry with the name Override, if it does not exist. Set its value to 0 (zero). This entry controls whether the Domino Journaling task reexamines any messages that are marked as MARK_DO_NOT_ARCHIVE each time it processes the Domino journaling location. If the value is 0, or the Override entry does not exist, then the Domino Journaling task does not reexamine the messages.

To implement changes to the registry settings, restart the associated Domino Journaling tasks.

Page 476: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

476 Filtering APIsEnumerations (Domino filtering)

Enumerations (Domino filtering)This section lists the enumerations for the Domino Filtering API.

Message direction enumerationThe following enumeration values are defined for MSG_DIRECTION:public enum MSG_DIRECTION { DIRECTION_UNDEFINED = 0, DIRECTION_INTERNAL = 1, DIRECTION_EXTERNAL_IN = 2, DIRECTION_EXTERNAL_OUT = 3

}

Domino action enumeration The following enumeration values are defined for DominoAction:

public enum DominoAction{

NO_ACTION = 0, ARCHIVE_ITEM = 1,MARK_DO_NOT_ARCHIVE = 2,HARD_DELETE = 4,REQUEST_SHUTDOWN = 5

}

Table 7-6 DominoAction enumeration values

Value Action

NO_ACTION Do not archive, delete or mark the item.

ARCHIVE_ITEM (Default) Archive the item according to the assigned policy.

MARK_DO_NOT_ARCHIVE Mark the item as processed but do not archive it. The Domino Journaling task does not reexamine marked messages unless the Override setting is configured.

See “Domino filtering registry settings” on page 474

HARD_DELETE Hard delete the item without archiving it.

Note that this option requires Enterprise Vault 8.0 SP5 or later.

REQUEST_SHUTDOWN Shut down the archiving task.

Page 477: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

477Filtering APIsEnumerations (Domino filtering)

Page 478: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

478 Filtering APIsIExternalFilter interface

IExternalFilter interfaceThe external filter must implement the IExternalFilter interface, which is called by the archiving task filter controller:

Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntaxpublic interface IExternalFilter

Member summary

Requirements

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.

Page 479: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

479Filtering APIsIExternalFilter :: Initialize

IExternalFilter :: Initialize This method is called during archiving task initialization.

Syntaxvoid Initialize();

RemarksFilters are instantiated at task startup and released at task shutdown.

The filter should perform any necessary initialization before item processing begins.

Page 480: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

480 Filtering APIsIExternalFilter :: ProcessFilter

IExternalFilter :: ProcessFilterThis method is called per-item during the archiving process. The ProcessFilter method is where you process the item to your requirements.

Syntaxvoid ProcessFilter(IArchivingControl archivingControl,

ref bool stopFiltering);

Parameters

RemarksThe archivingControl reference is used by the filter in the callback to obtain information about the current item and take appropriate actions.

As the archiving task runs in multiple threads, the external filter must be written to handle concurrent calls. If the filter accesses a shared resource, it must use appropriate concurrency protection.

See also■ “IArchivingControl interface” on page 483

■ “ILotusArchivingControl interface” on page 490

IArchivingControl archivingControl Reference to the LotusArchivingControl interface.

ref bool stopFiltering True value prevents any further filters from being processed for the current item.

Page 481: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

481Filtering APIsIExternalFilter :: FilteringComplete

IExternalFilter :: FilteringCompleteThis method is called after all filters have been processed.

Syntaxvoid FilteringComplete();

RemarksThis method can be used to clean up resources used to filter the item.

Page 482: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

482 Filtering APIsIExternalFilter :: Shutdown

IExternalFilter :: ShutdownThis method is called during archiving task shutdown.

Syntaxvoid Shutdown();

RemarksThe filter should perform any necessary clean-up tasks.

Page 483: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

483Filtering APIsIArchivingControl interface

IArchivingControl interfaceThis task filter controller implements the following interfaces:

■ IArchivingControl

■ ILotusArchivingControl

Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

The methods properties of the interfaces enable an external filter to retrieve and modify properties on the current item.

The ILotusArchivingControl interface is implemented by the Domino archiving task filter controller, and is passed to the filter on a per-message basis during the ProcessFilter call. It extends the IArchivingControl interface to provide access to Domino messages from Domino filters.

See “ILotusArchivingControl interface” on page 490

Syntaxpublic interface ILotusArchivingControl : IArchivingControl

Member summary

Table 7-7 IArchivingControl properties

Property Read/Write Description

OriginalVaultID Read only Original archive for the current item.

CurrentVaultID Read/Write Target archive for the current item.

OriginalRetentionCategoryID Read only Original retention category for the current item.

CurrentRetentionCategoryID Read/Write Retention category assigned to current item.

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

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

Page 484: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

484 Filtering APIsIArchivingControl :: OriginalVaultID

IArchivingControl :: OriginalVaultIDRetrieves the original archive ID for the current item.

This property is read-only.

Syntaxstring OriginalVaultID {get;}

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

Page 485: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

485Filtering APIsIArchivingControl :: CurrentVaultID

IArchivingControl :: CurrentVaultIDThis property retrieves or sets the ID of the archive in which the current item will be stored.

This property is read/write.

Syntaxstring CurrentVaultID {get; set;}

ExampleAn example value for this property is:190901BF3D1D1364084C418053F8122C31110000EVArchiveSite1

Page 486: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

486 Filtering APIsIArchivingControl :: OriginalRetentionCategoryID

IArchivingControl :: OriginalRetentionCategoryIDThis property holds the original retention category ID for the current item.

This property is read-only.

Syntaxstring OriginalRetentionCategoryID {get;}

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

Page 487: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

487Filtering APIsIArchivingControl :: CurrentRetentionCategoryID

IArchivingControl :: CurrentRetentionCategoryIDThis property defines the retention category for the current item.

This property is read/write.

Syntaxstring CurrentRetentionCategoryID {get; set;}

RemarksUse this property to set or retrieve the ID of the retention category assigned to the current item.

An example value is:18306BF113C2C444096279660836252821b10000EVArchiveSite1

Page 488: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

488 Filtering APIsIArchivingControl :: IndexData

IArchivingControl :: IndexDataThis 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.

SyntaxIIndexMetadata IndexData {get;}

Remarks

See also■ “IIndexMetadata interface” on page 499.

Page 489: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

489Filtering APIsIArchivingControl :: FilterProperties

IArchivingControl :: FilterPropertiesThis 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.

SyntaxIKeyedList FilterProperties {get;}

RemarksThe properties listed are shared across all filters. These properties are not stored in Enterprise Vault or reset by Enterprise Vault. The properties can be maintained across multiple messages, if required.

See also■ “IKeyedList interface” on page 513.

Page 490: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

490 Filtering APIsILotusArchivingControl interface

ILotusArchivingControl interfaceILotusArchivingControl is derived from the IArchivingControl interface, and extends the interface to enable filters to access Domino messages.

Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

For details of the properties on the IArchivingControl interface, see“IArchivingControl interface” on page 483

Member summary

Table 7-8 ILotusArchivingControl properties

Property Read/Write Description

Action Read/Write Defines filtering action for current message.

NoteHandle Read only Handle to current message.

DatabaseHandle Read only Handle to current journal database.

DatabaseName Read only Path to current journal database.

SenderRecipientXML Read only XML representation of message distribution list.

StoreIdentifier Read only Unique Id of Domino message.

Direction Read only Direction of message (internal or external).

Page 491: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

491Filtering APIsILotusArchivingControl :: Action

ILotusArchivingControl :: ActionThis property defines the filtering action for the current message.

The property is read/write.

SyntaxDominoAction Action {get; set;}

RemarksThe filtering action is defined by the DominoAction enumeration. For DominoAction enumerated values, see “Domino action enumeration” on page 476.

The default action is to archive the item (ARCHIVE_ITEM enumeration value).

Page 492: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

492 Filtering APIsILotusArchivingControl :: NoteHandle

ILotusArchivingControl :: NoteHandleThis property retrieves the Lotus C API for Lotus Notes/Domino handle to the current message.

The property is read only.

SyntaxIntPtr NoteHandle {get;}

RemarksThis handle must not be closed by the filter.

Page 493: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

493Filtering APIsILotusArchivingControl :: DatabaseHandle

ILotusArchivingControl :: DatabaseHandleThis property retrieves the Lotus C API for Lotus Notes/Domino handle to the current database.

The property is read only.

SyntaxIntPtr DatabaseHandle {get;}

RemarksThis handle must not be closed by the filter.

Page 494: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

494 Filtering APIsILotusArchivingControl :: DatabaseName

ILotusArchivingControl :: DatabaseNameThis property retrieves the current Domino journal database path.

The property is read only.

Syntaxstring DatabaseName {get;}

RemarksThis path is relative to the Data folder.

Page 495: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

495Filtering APIsILotusArchivingControl :: SenderRecipientXML

ILotusArchivingControl :: SenderRecipientXMLThis property retrieves an XML document containing the sender and recipient information for the current message.

The property is read only.

SyntaxXmlDocument SenderRecipientXML {get;}

RemarksAny distribution lists are expanded, regardless of the setting of the Expand distribution lists setting on the Advanced page of the Domino Journaling policy in the Enterprise Vault Administration Console.

The property value is an XML document representing the sender and recipient information for the current message, including expanded distribution lists.

This document is described by the following DTD:<!ELEMENT MSG (RECP, AUTH)><!ELEMENT RECP (TO, CC, BCC)><!ELEMENT TO (RC*, DL*)><!ELEMENT CC (RC*, DL*)><!ELEMENT BCC (RC*, DL*)><!ELEMENT RC (DN, EA+)><!ELEMENT DN (#PCDATA)><!ELEMENT EA (#PCDATA)><!ELEMENT DL (DN, EA, RC*)><!ELEMENT AUTH (FROM, PP)><!ELEMENT FROM (DN, EA)><!ELEMENT PP (DN?, EA?)><!ATTLIST EA TYPE CDATA #REQUIRED>

Example The following is an example of the SenderRecipientXML document: <!--The <RECP> element lists all the message recipients in TO, CC, BCC fields. If distribution lists are present, the name and address of the distribution list is given in the <DL> element and member addresses are listed in <RC> elements --><MSG>

<RECP><TO>

<RC><DN>Display Name</DN> <EA TYPE="SMTP">SMTP_address</EA><EA TYPE="NOTES">LotusNotes_address</EA>

</RC>

Page 496: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

496 Filtering APIsILotusArchivingControl :: SenderRecipientXML

<DL><DN>Display Name of DL</DN> <EA TYPE="NOTES">lotusnotes_address_of_dl</EA> <RC>

<DN>Display Name of DL Member</DN><EA TYPE="NOTES">lotusnotes_address_of_dl_member</EA>

</RC></DL>

</TO><CC/><BCC/>

</RECP><!--The <AUTH> element gives the display name, SMTP and Lotus Notes format addresses for the message author. If the message was sent by a delegate, the principal person is defined in the <PP> element -->

<AUTH><FROM>

<DN>Display Name</DN> <EA TYPE="NOTES">LotusNotes_address</EA>

</FROM><PP/>

</AUTH></MSG>

Page 497: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

497Filtering APIsILotusArchivingControl :: StoreIdentifier

ILotusArchivingControl :: StoreIdentifierThis property uniquely identifies the message.

The property is read only.

Syntaxstring StoreIdentifier {get;}

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

Page 498: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

498 Filtering APIsILotusArchivingControl :: Direction

ILotusArchivingControl :: DirectionThis property indicates the direction in which the message was travelling (in relation to the domain defined as internal).

SyntaxMSG_DIRECTION Direction {get;}

RemarksThe property value is an enumerated value. For MSG_DIRECTION enumerated values, see “Message direction enumeration” on page 476.

Page 499: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

499Filtering APIsIIndexMetadata interface

IIndexMetadata interfaceThis interface enables the external filter to add properties to the custom index metadata for the current item, and retrieve additional properties that have been previously added to the index using Add ().

Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntaxpublic interface IIndexMetadata : IEnumerable

Member summary

RemarksThe IIndexMetadata interface inherits from the IEnumerable interface and hence supports standard enumeration support for the collection of properties. When enumerating, each property is returned as an instance of the IIndexProperty interface.

See “IIndexProperty interface” on page 507.

Table 7-9 IIndexMetadata properties

Property Read/Write Description

DateTimeUTC Read/Write Whether date and time properties are UTC or local system time.

Table 7-10 IIndexMetadata methods

Method Description

Count Returns the current count of properties.

Add Add a custom index metadata property to the current item.

Clear Remove all custom index metadata properties from the current item.

ToXML Persists the custom index metadata to XML.

FromXML Loads the custom index metadata from XML.

Page 500: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

500 Filtering APIsIIndexMetadata :: ToXML

IIndexMetadata :: ToXMLThis method returns the custom index metadata as an XML document.

Syntaxstring ToXML(bool formattedLayout);

Parameters

RemarksThe XML can be loaded into an ISimpleIndexMetadata object, as defined in the Content Management API.

See “SimpleIndexMetadata object” on page 277.

bool formattedLayout If true, the XML returned will be formatted in lines and indented appropriately.

Page 501: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

501Filtering APIsIIndexMetadata :: FromXML

IIndexMetadata :: FromXMLThis method loads the custom index metadata from an XML document.

Syntaxvoid FromXML(string xmlIndexMetadata);

Parameters

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

[in] BSTR xmlIndexMetadata The XML stream to input.

Page 502: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

502 Filtering APIsIIndexMetadata :: 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.

Syntaxvoid 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

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

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.

Page 503: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

503Filtering APIsIIndexMetadata :: Add

Properties can be multi-valued. When adding a property, the existence of that property within the specified property set is checked and, if present, the value is added as an element of that property.

If the Searchable property is true, the property will be indexed.

If the Retrievable property is true, the property is stored with the item in the archive. The property information can then be retrieved and displayed later with the item in search results. The default value is false.

It is good practice to use a named property set in order to avoid name clashes with other external filter additions. Suitable names would be your company name or the filter application name. The following property set names are reserved:

■ Vault

■ EnterpriseVault

■ KVS

■ Veritas

■ Symantec

Property sets do not need to be created before properties are added to them. When you use Add() to add a property to the index, the property will be added to the property set specified by propertySet, if the property set exists. If the set does not exist, it will be created first.

Page 504: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

504 Filtering APIsIIndexMetadata :: Clear

IIndexMetadata :: ClearThis method clears all properties from the IIndexMetadata object for the current item.

Syntaxvoid Clear();

Page 505: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

505Filtering APIsIIndexMetadata :: Count

IIndexMetadata :: CountThis method retrieves the number of properties in the IndexMetadata object for the current item.

Syntaxint Count();

Page 506: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

506 Filtering APIsIIndexMetadata :: DateTimesUTC

IIndexMetadata :: DateTimesUTCThis property sets or retrieves whether the date and time properties are input and output in UTC or local system time.

Syntaxbool DateTimeUTC {get; set;}

RemarksThis property sets or retrieves whether the date and time properties are input and output in UTC or local system time.

Page 507: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

507Filtering APIsIIndexProperty interface

IIndexProperty interfaceThe IIndexProperty interface details a a custom index metadata property within an IIndexMetadata collection.

Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntaxpublic interface IIndexProperty

Member summary

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

}

Table 7-11 IIndexProperty properties

Property Read/Write Description

Set Read only The name of the property set.

Name Read only The name of the property.

Value Read only The value assigned to the property.

Searchable Read only Defines whether the property is to be added to the item index.

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

Page 508: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

508 Filtering APIsIIndexProperty :: Set

IIndexProperty :: SetThis property holds the name of the property set.

The property is read only.

Syntaxstring Set {get;}

Page 509: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

509Filtering APIsIIndexProperty :: Name

IIndexProperty :: NameThis property holds the name of the custom index property.

The property is read only.

Syntaxstring Name {get;}

Page 510: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

510 Filtering APIsIIndexProperty :: Value

IIndexProperty :: ValueThis property holds the value of the index property.

The property is read only.

SyntaxSystem.Object Value {get;}

RemarksThe object will be a string, integer, or date/time value.

Example

C#IIndexMetadata custProps = archivingControl.IndexMetadata;

foreach(IIndexProperty prop in custProps){

if (prop.Searchable && (prop.Value.GetType() == typeof(DateTime)))

{ searchableDateProps.Add(prop.Set, prop.Name,

(DateTime)prop.Value);}

}

Page 511: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

511Filtering APIsIIndexProperty :: Searchable

IIndexProperty :: SearchableThis property indicates whether the property can be returned in search results when using the Search API.

The property is read only.

Syntaxbool Searchable {get;}

Page 512: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

512 Filtering APIsIIndexProperty :: Retrievable

IIndexProperty :: RetrievableThis property indicates whether the index property can be retrieved and displayed with search results when using the Search API.

The property is read only.

Syntaxbool Retrievable {get;}

Page 513: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

513Filtering APIsIKeyedList interface

IKeyedList interfaceThis interface enables multiple filters to access a list of filter properties. The collection allows both random access by index and keyed access using a key value.

Assembly: KVS.EnterpriseVault.LotusDominoInterfaces.DLL

Syntax public interface IKeyedList : ICollection, IDictionary, IEnumerable

Member summary

See also■ “IArchivingControl :: FilterProperties” on page 489.

Table 7-12 IKeyedList methods

Method Description

Insert Inserts a filter property into the list at the specified position.

RemoveAt Removes a filter property from the specified position in the list.

Page 514: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

514 Filtering APIsIKeyedList :: Insert

IKeyedList :: InsertInserts a filter property into the list at the specified position.

Syntaxvoid Insert(System.Int32 index, System.Object key,

System.Object value);

Parameters

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

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.

Page 515: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

515Filtering APIsIKeyedList :: RemoveAt

IKeyedList :: RemoveAtRemoves a filter property from the list at the specified position.

Syntaxvoid RemoveAt(Int32 index);

Parameter

RemarksThe elements that follow the removed element move up to occupy the vacated spot.

An exception is reported if the index is out of range.

Int32 index The position in the list.

Page 516: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

516 Filtering APIsIKeyedList :: RemoveAt

Page 517: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Chapter

8

Search API

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

Introduction to storing and indexingThe Enterprise Vault Storage service accepts items for archiving from the archiving tasks. If possible, it generates a text or HTML version of each item, which the Indexing service uses to compile indexing data for the item. The Storage service compresses and stores the items (and the text or HTML versions) as savesets in the appropriate archives. Information about each item that is archived is stored in the vault store database. The Storage service also responds to requests from the retrieval tasks to restore items.

The Indexing service manages the indexes of archived data to enable users to search for archived items that they want to retrieve. The role of the Indexing service can be summarized as follows:

■ On instruction from the Storage service, the Indexing service indexes items as they are archived. There can be one to many indexes (index volumes) per archive.

The locations of index files are specified in the Indexing service properties in the Enterprise Vault Administration Console.

■ In response to search requests from the Enterprise Vault Web access components, or third-party search applications using the Search API, the Indexing service searches these indexes and returns information about the archived items that match the search criteria.

■ The Indexing service ensures that indexes are complete and up to date. If an index is out of date, the Indexing service automatically updates the index.

In Enterprise Vault you can set the required level of indexing. If required, different levels can be set for different groups of users. There are three levels of

Page 518: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

518 Search APIIntroduction to storing and indexing

indexing: brief, medium and full. Each level extends the searches that users can perform:

■ Brief indexing. This enables users to search on attributes of an archived item such as Author, Subject, Recipients, Created Date, File Extension, Retention Category and so on. With brief indexing, the content of the item is not indexed.

■ Medium indexing. This enables users to search attributes, as for brief indexing, as well as searching content. It does not provide phrase searching in content.

■ Full indexing. This enables users to search as for medium indexing, and also provides searching for phrases in content.

Obviously, the more information that is indexed, the more disk space is required for the index.

For example, for brief indexing, the index size is approximately 3% of the size of the data that is indexed. For medium indexing, the figure is approximately 8% and for full it is approximately 12% (depending on the type of documents).

The level of indexing, and when an item is indexed for a particular archive can be controlled using the Content Management API.

See “IArchive :: IndexLevel” on page 136.

See “IArchive :: IndexUrgency” on page 134.

The content and attachments are indexed if there is a content converter available for the file type, and the converted content does not exceed the configured size limits (by default, 30 MB after conversion to HTML or text).

If the content cannot be indexed, a 'content missing' reason is indexed using the "comr" property.

See “System properties” on page 664.

See “ETruncationReason enumeration” on page 536.

Enterprise Vault indexesEach archive index comprises one or more sequential index volume sets. An index volume set contains an index volume. (Currently, an index volume set can contain only one index volume). Each index volume contains index entries for the items stored in the archive. Each Enterprise Vault archive can have one or more associated index volumes.

When an index volume is full, the Enterprise Vault Indexing service automatically creates a new index volume (in a new index volume set). The Enterprise Vault administrator uses the Enterprise Vault Administration Console to configure the physical locations to be used by the Indexing service when creating new indexes and index volumes.

Page 519: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

519Search APIUsing the Search API

Figure 8-1 An archive index

Typically, user mailbox indexes require only a single volume. Indexes for larger archives, such as file system archives and journal archives, are quite likely to have multiple volumes.

When a user or application performs a search on an archive, the search is performed on index volumes associated with the archive, not the archive itself.

For more information on Enterprise Vault indexes, see “About index volume sets and volumes” on page 659.

Using the Search APIFor programming notes on using Enterprise Vault APIs with .NET managed code, and information about code samples in this manual, see “Programming notes” on page 46.

All the components required for using the Search API are contained in IndexClient.dll.

■ SearchQuery object is used to construct search queries.

Page 520: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

520 Search APIUsing the Search API

■ IndexVolumeSets object enables access to a collection of IndexVolumeSet objects.

■ IndexVolumeSet object provides properties that expose information about the index volume set.

■ IndexSearch2 object is used to select an index to search, and submit a search query to return some search results.

■ SearchResults object is used to enumerate through a set of search results.

■ SearchResult object is used to enumerate through the index property values returned for each search hit (search result).

The process of using the Search API is, brief, as follows:

■ Get an instance of the Search Query object. You can do this in the usual manner using CoCreateInstance directly (C++), or indirectly using the new operator (.NET managed code).

■ Build the query. You do this by adding various terms and operations to the query object using the ISearchQuery2 interface properties and methods.

See “Constructing a search query” on page 520

■ Get an instance of the IndexSearch2 object and submit the search by calling the Search method of IndexSearch2 interface.

See “Performing a search” on page 524

■ This returns a SearchResults object, which in turn is used get SearchResult object instances for each of the search hits returned in the SearchResults object. (You do not have to obtain or create the SearchResults or SearchResult objects).

See “Processing the search results” on page 527

Constructing a search queryTake 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

Page 521: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

521Search APIUsing the Search API

In order to find the correct emails, we need to attach search conditions to each of these properties:

■ Author - is either John Doe or Alan Smith

■ Subject - this must contain the phrase "Financial Reports"

■ Document Date - this must be earlier than 17th May 2001

The words in italics are the operators within the query.

The Search API does not have a "less than" or "greater than" operator so it will be necessary to use a Range for the Document Date:

■ Document Date - this must be between 1st January 1900 and 16th May 2001

The query can now be rewritten as follows:

Find All emails where Author = ("Fred Bloggs" or "John Smith") and (Subject contains the phrase "Financial Reports") and (Document Date is between "1st January 1900 and 17th May 2001")

The property name, for example, Author, would normally be one of the Enterprise Vault system index property names.

“System properties” on page 664.

In addition to system property names, custom properties defined by the user can also be used.

Any number of terms can be added to a SearchQuery object. By default, they are all combined using the AND operator. Different operators can be specified using the Combine, AddOp, or AddQuery methods:

■ Combine takes two SearchQuery objects, each containing one or more terms and an operator. The method creates a new search query containing all the terms in both objects, combined with the specified operator. This new query can be used in a further Combine operation to create searches of arbitrary complexity.

■ AddQuery is similar to Combine, but instead of taking two SearchQuery objects and combining them to create a third, it incorporates the second object into the first.

■ AddOp combines one or more of the terms previously added to the SearchQuery object with the specified operator.

All three methods can be used interchangeably, and at different stages in the construction of a single search query. Which approach you use depends solely on your preference.

To start to construct the earlier example query, you use the AddTerm method of the ISearchQuery interface. AddTerm has the parameters: property, value, search query flag. If SetTerm is used, it clears out any previous query.

Page 522: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

522 Search APIUsing the Search API

The search query flag determines how to process individual terms added to a search query.

See “ESearchQueryFlags enumeration” on page 533.

The first term could be added to the query as follows:AddTerm(IndexPropAUTH, "John Doe", ESQPhrase);

Then the second term could be added to the query as follows:AddTerm(IndexPropAUTH, "Alan Smith", ESQPhrase);

Now the above terms need to be combined using the OR operator. This is done using the AddOp method:AddOp(ESQor, ESQBinary)

The query is built up using a reverse polish system; the operator is applied to the previous x 'objects' to create a new one, where x is determined by the value of the second parameter to AppOp, the search object scope.

See “ISearchQuery :: AddOp” on page 554.

The operator itself can be obtained from the ESearchQueryOperators enumeration.

See “ESearchQueryOperators enumeration” on page 534.

In the example query, two more terms can now be added; the Subject term and the date range term:AddTerm(IndexPropSubj, "Financial Results", ESQPhrase)AddRange(IndexPropDate, 1st January 1900, 16th May 2001, ESQany)

(In reality, you would use the appropriate DateTime object for the programming language being used).

The three parts of the query need to be combined using the AND operator. (The first part is the result of the first call to AddOp. The second and third parts are the terms being added in this operation):AppOp(ESQand, ESQQternary)

The resulting query now represents the original query that was expressed in words. The constructed query can be used by the Search method of the IndexSearch2 interface to search the index of an archive.

The search query operator, ESQfilter, is a special operator for performing complex searches, such as those required by the Enterprise Vault Compliance and Discovery Accelerator products.

See “ESQfilter searches” on page 522.

ESQfilter searchesESQfilter is similar to ESQ but more powerful. The following summarizes how this operator works:

Page 523: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

523Search APIUsing the Search API

■ A search is performed using the first query. This searches top-level items only. (For example, this term could specify a date range to be searched).

■ A separate search is performed using subsequent queries. This searches both top-level items and attachments. (For example, words in message subject or content).

■ The results are compared and any result from the second search which has an associated top-level item that matches a result from the first query search is added to the results.

Only top-level items are returned in results; if a search query is satisfied in an attachment, the associated top-level item is returned in results.

Note that the Options setting of the Search method is ignored if the search uses the operator ESQfilter.

This type of search is particularly efficient for compliance or discovery type searches. For optimum performance, it should be used together with the ItemGranularityOnly index schema.

See “About index schemas” on page 660.

Special characters in search queriesIn 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.

Page 524: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

524 Search APIUsing the Search API

There must be at least three other characters before a wildcard.

Finally, words like "and" and "or" have no special meaning in query values (and cannot be given any special meaning). They will be searched for like any other word. So, for example, to search for documents containing both "financial" and "hint", search for the string "financial hint" using ESQall.

Performing a searchThe index is searched using the methods and properties of the IIndexSearch2 interface.

Before initiating the search, set requirements for the search and search results using methods and properties of the IIndexSearch2 interface:

■ SelectArchive method. Use this to specify the index to search. The index is identified using the Id of the associated archive.

You can use the vault store and archive enumeration functionality in the Content Management API to find the target archive.

The Id of an archive can also be discovered using the Enterprise Vault Administration Console:

■ In the Enterprise Vault Administration Console, double-click the archive to display the properties dialog and click the Advanced tab. The archive Id is displayed on the advanced properties page.

■ SelectIndexVolumeSet method. If you do not want Enterprise Vault to perform a federated search across multiple index volumes, use this method to set the Id of the archive's index volume set to search.

See “Searching indexes with multiple volume sets” on page 525

■ Options property. Use this to set the required granularity of the search:

■ roItemGranularity. Only top-level items are searched, not attachments.

■ roAttachmentGranularity. Both top-level items and attachments are searched.

Note that the Options setting is ignored if the search uses the operator ESQfilter.

See “ESQfilter searches” on page 522

■ AdditionalResultsProperties property. Use this to set the required properties to be returned in results. (Use AdditionalResultsProperties in preference to the ResultsPropertySet property).

■ SortBy property. Use this to specify the required sort order of the results.

After setting the required properties, you initiate the search using the Search method.

Page 525: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

525Search APIUsing the Search API

The query is passed to this method as a query string. In most cases this query string is created using the methods of ISearchQuery2 interface. The Query property returns the string that has been constructed and can be passed to the Search method.

Use the Search method parameters, startResult and maximumResults to specify the number of results to return at one time. This enables you to "page" through the results.

The output from a search is a pointer to a SearchResults object, which provides a structured way to access the results. The object provides standard collection support enabling iterative operations on the results in the collection, such as "for each" in Visual Basic, and .NET managed code.

Concurrent searchesTo optimize performance, applications using multiple search threads should search different archives or index volume sets.

Searching indexes that are changing during the searchIt 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 setsEnterprise 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.

Page 526: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

526 Search APIUsing the Search API

■ An archive has multiple index volumes, and the number of index volumes is less than, or equal to MaxSearchIndexVolumeSets (default 5).

If an archive has more than five index volumes, then you can either increase the number to be searched by setting the value of MaxSearchIndexVolumeSets, or use SelectIndexVolumeSet to select the index volume set to search.

Use MaxSearchResultsPerVolumeSet to set the maximum number of results per volume set that can be processed and merged during a federated search (default is 1000).

Be aware that increasing these default settings could result in a time out.

If it is necessary to select a specific volume set then after calling SelectArchive, a call to IndexVolumeSets returns a collection of IIndexVolumeSet pointers from which the ID can be obtained.

See “IndexSearch object” on page 564.

Creating multiple index volume sets for testingIn a test environment, an archive typically only has one index volume set because the number of archived items is relatively low. However, there are several properties and methods that are only tested when multiple index volume sets exist. In particular, when developing non-federated search applications, the scope for testing is very limited if there is only one index volume set available.

You can use the registry setting, AVSMaxLoc, to create multiple index volume sets for testing purposes. This setting lets you configure the number of index locations used before a new index volume set is created.

Setting name

Setting location

Content Description

AVSMaxLoc HKEY_LOCAL_MACHINE\SOFTWARE\KVS\Enterprise Vault\Indexing

DWORD.

Default value is 1,000,000,000

Maximum location value allowed in an index.

Typically used to prevent indexes from exceeding their maximum size.

In test scenarios, can be used to create multiple index volume sets.

Can be specified per index by creating the values below a key with value equal to the Index entry-id.

Page 527: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

527Search APIUsing the Search API

To create multiple volume index sets for testing

1 Ensure that the archive's indexing level is set to Full.

2 Open regedit, and navigate to the Indexing registry key at the location shown above. If either the Indexing key or AVSMaxLoc do not exist, then create them.

3 Set the value of AVSMaxLoc to something like 2,500,000. It must have a value greater than 2,000,000.

4 Archive items with large content or attachments that contain a large number of words.

Continue to archive large items until six or more index volumes have been created. (If AVSMaxLoc is set to 2,500,000, this would mean that approximately 6 * 2,500,000 words have been indexed).

This ensures that the number of index volumes is greater than the default federation search threshold (5), and should ensure that there are more items per index volume than the default maximum results per index volume for federation searches (1000).

Alternatively, if you already have a large test index, you can change the value of AVSMaxLoc and then rebuild the index using the Enterprise Vault Administration Console. The option for rebuilding indexes is on the Index Volumes tab of Archive properties in the Enterprise Vault Administration Console.

Processing the search resultsThe SearchResults object is a collection of results returned by IndexSearch. (The implementation of ISearchResults2 contains a collection of ISearchResult2 interface pointers). The first result in the collection, and the maximum number of results returned in the collection are defined by the startResult and maximumResults parameters to the Search method.

The SearchResults object has several properties, including the following:

■ Count. This is the number of results in the object; that is, the size of the current collection.

■ Total. This is the total number of results for the search.

You can access the data for each result returned using the methods of ISearchResult2.

Only top-level items are returned in results if any of the following are configured:

■ Searching is limited to top-level items using roItemGranularity option in the Search method.

Page 528: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

528 Search APIUsing the Search API

■ The search query includes the ESQfilter operator. Attachments are searched but the associated top-level item is returned in results.

■ The ItemGranularityOnly index schema is enabled. Attachments are searched but the associated top-level item is returned in results.

Remember, a search result is not the archived item; it is a set of properties containing information about the item. To retrieve the archived item, use the Get method of the IItem interface in the ContentManagementAPI.

See “IItem :: Get” on page 200.

To access the properties of each result, use the Prop method of the SearchResult class, specifying the required property as the parameter.

Enterprise Vault index propertiesEnterprise Vault index properties are listed in “System properties” on page 664. When using the Search API, Enterprise Vault property names are defined as constants in the form IndexPropXXXX. See “Index Property constants” on page 533.

There are Enterprise Vault system properties and custom properties. Custom properties are typically defined and added as items are archived by third-party components using the APIs and plug in points provided by Enterprise Vault.

Properties are defined as searchable, or retrievable or both:

■ Searchable means that the property can be used in search queries to find items in the archive index.

■ Retrievable means that the property can be returned in search results.

Custom properties can be referenced using propertySet.propertyName, with propertySet empty for the global property set. In many cases there are custom property specific versions of methods that allow the propertySet and propertyName string separately.

Search API ExampleShown here are two methods that demonstrate a search.

The first method, 'SearchArchive’, takes an archive Id and the maximum number of search results as parameters. 'SearchArchive' compares the number of Index Volume Sets in the archive against the value of the property IIndexSearch2::MaxSearchIndexVolumeSets to determine whether a federated or non-federated search is required.

The second method 'DoSearch' is then called. 'DoSearch' takes two parameters, the IndexSearch2 object created in 'SearchArchive', and the maximum number

Page 529: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

529Search APIUsing the Search API

of search results. If the search is not a federated search, then this second parameter is zero.

void SearchArchive(string archId, int maxSearchResults){

IIndexSearch2 search = (IIndexSearch2) new IndexSearch2();

//First select the archivesearch.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 archiveIIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;

long count = volSets.Count;

//use this count value to see which approach to takeif (count > search.MaxSearchIndexVolumeSets){

//do non-federated searchforeach (IIndexVolumeSet volSet in volSets){

search.SelectIndexVolumeSet(volSet.Identity);DoSearch(search, 0);

}}else{

DoSearch(search, maxSearchResults);}Marshal.FinalReleaseCOMObject(search);

}

The DoSearch method, called from 'SearchArchive' performs the actual search on the entire archive, or the specifed Index Volume Set, depending on whether or not the search is a federated search.

The search will filter on a range of archived dates, a phrase in the subject, greater than zero attachments and the author.

The retrieved properties are created date, content (first 150 characters only), saveset Id, number of attachments, subject, TO:recipient, CC:recipient, BCC:recipient.

Typically the property values in the query would be supplied using a GUI or a command line. However, for the purposes of this example, they are supplied in the code.

Page 530: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

530 Search APIUsing the Search API

void DoSearch(IIndexSearch2 search, int maxSearchResults){

ISearchQuery2 query = (ISearchQuery2) new SearchQuery2();

DateTime dtFrom = new DateTime(2007, 1, 1);DateTime dtTo = new DateTime(2007, 12, 31);

query.SetRange("adat", dtFrom, dtTo, (int)ESearchQueryFlags.ESQany);query.AddRange("natc", 0, 10000, (int)ESearchQueryFlags.ESQany);query.AddTerm("subj", "a phrase in the subject",

(int)ESearchQueryFlags.ESQphrase);query.AddTerm("auth", "joe.user", (int)ESearchQueryFlags.ESQexact);query.AddOp((int)ESearchQueryOperators.ESQand, 4);

search.SortBy = "snum";

//if this is a federated search then set the maximum number of search//results per index volume set//if this is not a federated search then 'maxSearchResults' will be 0 and'MaxSearchResultsPerVolumeSet' will not be used.if (maxSearchResults > 0)

search.MaxSearchResultsPerVolumeSet = maxSearchResults;

//we are going to search top level items onlysearch.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 tostart returning the result set

int count = 0;

ISearchResults2 results = null;

do{

results = (ISearchResults2)search.Search(query.Query, start, 500, "");

if (results.InSync == true){

if (results.TruncationReason == ETruncationReason.trNone){

//make sure that date time properties are returned as local//system time not UTCresults.DateTimesUTC = false;

Page 531: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

531Search APIUsing the Search API

foreach (ISearchResult2 result in results){

DateTime createdDate = (DateTime)result.Prop("date");string ssid = (string)result.Prop("ssid");int numAttach = (int)result.Prop("natc");string subj = (string)result.Prop("subj");string reto = (string)result.Prop("reto");string rbcc = (string)result.Prop("rbcc");

//do something with the results}

}else{

ETruncationReason tr = (ETruncationReason)results.TruncationReason;switch (tr){

case ETruncationReason.trAdminResultLimitExceeded://do somethingbreak;case ETruncationReason.trAdminTimeoutExpired://do somethingbreak;case ETruncationReason.trItemsOrContentMissing://do somethingbreak;case ETruncationReason.trNotSearchedOrFailedVolumes://do somethingbreak;case ETruncationReason.trResultLimitExceeded://do somethingbreak;case ETruncationReason.trTimeoutExpired://do somethingbreak;case ETruncationReason.trWidthNormalizationRequired://do somethingbreak;

}}

}else{

MessageBox.Show("It is possible that the index was being updated as thesearch was being carried out","Index not synchronised?", MessageBoxButtons.OK,MessageBoxIcon.Warning);

}count = results.Count;Marshal.FinalReleaseCOMObject(results);results = null;

Page 532: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

532 Search APIUsing the Search API

start += 500;}while (count != 0);

Marshal.FinalReleaseCOMObject(query);

}

Page 533: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

533Search APIConstants and enumerations

Constants and enumerationsThis section describes the constants and enumerations used by the Search API.

Index Property constantsWhen using the Search API, Enterprise Vault property names are defined as constants, where IndexPropXXXX is the constant for the property name, xxxx, in Table B-1 on page 664. For example, IndexPropSUBJ is the constant for the Enterprise Vault defined property, "subj", and IndexPropRCAT is the constant for the Enterprise Vault system property, "rcat".

ESearchQueryFlags enumerationESearchQueryFlags specify how to process individual terms added to a search query (for example, using AddTerm).

Note: From Enterprise Vault 10, the Search API will not support the following search operators for newly indexed items:

Using these search operators against items that were indexed using Enterprise Vault 9 or earlier will continue to be supported.

enum ESearchQueryFlags{// Exactly one of these must be present (default is ESQany)

ESQany = 0, // Contains any of the wordsESQall = 1, // Contains all the wordsESQallnear = 2, // Contains all the words, near each other

(within 10 words)ESQphrase = 3, // Contains all the words, in order (a phrase)ESQbeginany = 4, // Begins with any of the wordsESQbegins = 5, // Begins with all the words in order (a phrase)ESQexactany = 6, // Field exactly matches any of the wordsESQexact = 7, // Field exactly matches all the words, in order

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

Page 534: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

534 Search APIConstants and enumerations

ESQendsany = 8, // Ends with any of the wordsESQends = 9, // Ends with all the words in order (a phrase)ESQmatchmask = 15, // Mask to isolate above values from

flags below// Zero or more of the following may be present

ESQrank = 64, // Use words for results rankingESQusermask = 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 enumerationESearchOperatorScope 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

Page 535: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

535Search APIConstants 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 enumerationEOptionsFlags 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 enumerationEPropertySets are the predefined property sets that can be requested in search results.

As the predefined property sets may change at future releases, we recommend that you set this property to 0 (psEmpty) and use “IIndexSearch2 :: AddAdditionalResultsProperty” and “IIndexSearch2 :: AddAdditionalResultsCustomProperty” to set the required properties to be returned in the results set.enum EPropertySets

{psEmpty = 0,psWABrief = 1,// defaultpsWAMedium = 2,psWAFull = 3,psAEMailbox = 4,psAEFSA = 5,psAESPS = 6,psAEMultiFolders = 7,psCompliance = 8,psItemIds = 9,// Min set of ids needed to retrieve the item.psAEShared = 10,psAEJournal = 11,psAEPublicFolder = 12,psAESharePoint = 13

};

Page 536: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

536 Search APIConstants and enumerations

ETruncationReason enumerationETruncationReason explains why not all search results have been returned.enum ETruncationReason

{trNone = 0,trResultLimitExceeded = 1,trTimeoutExpired = 2,trAdminResultLimitExceeded = 4,trAdminTimeoutExpired = 8,trNotSearchedOrFailedVolumes = 16,trItemsOrContentMissing = 32,trWidthNormalizationRequired = 64

};

trNotSearchedOrFailedVolumes applies to federated searches only. The index contents for the whole archive cannot be listed. This can occur when one or more of the index volume sets are in a failed state; they could be, for example, offline or corrupt.

trItemsOrContentMissing indicates that index entries are missing for items or content in archive.

trWidthNormalizationRequired is set for old indexes where character width normalization was not applied to East Asian languages.

See http://entsupport.symantec.com/docs/289566

EXMLResultsFormatOptions enumerationEXMLResultsFormatOptions enumerates the XML format option values. Currently there is only one value:

enum EXMLResultsFormatOptions{

xoNone = 0x00000000// default};

Page 537: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

537Search APISearchQuery object

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

Syntaxinterface ISearchQuery2 : ISearchQuery : IDispatch

Member summary

Property Read/Write Description

ISearchQuery :: Query Read/Write The search query string.

Method Description

ISearchQuery :: Clear Discards the query currently being constructed in the object (if any), and resets the object so that it is ready for a new query.

ISearchQuery :: SetTerm Implements Clear, followed by AddTerm.

ISearchQuery :: AddTerm Adds a search term to the query.

ISearchQuery :: SetRange Implements Clear followed by AddRange.

ISearchQuery :: AddRange Adds a date or integer range to the query.

ISearchQuery :: SetProperty Implements Clear followed by AddProperty.

ISearchQuery :: AddProperty Adds a property to the query.

ISearchQuery :: AddOp Adds an operation to the query.

ISearchQuery :: Combine Combines two search queries with an operator.

ISearchQuery :: AddQuery Similar to combine, but combines a query with the query already in the object.

Page 538: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

538 Search APISearchQuery object

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

RequirementsSee “Programming notes” on page 46.

ExampleThe object 'query' constructed here will be used in the most of the following examples. It is shown here as a private class data member.

ISearchQuery2 :: SetPropertyRange Equivalent of SetRange method. Enables use of date and integer ranges for custom properties in queries.

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

Method Description

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

Page 539: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

539Search APISearchQuery object

C#public class SampleSearchClass{

private ISearchQuery2 query = (ISearchQuery2) new SearchQuery();

//rest of the class

Page 540: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

540 Search APIISearchQuery :: Query

ISearchQuery :: QueryThe Query property is the default property. It returns a string containing the query previously constructed.

The property is read/write.

SyntaxHRESULT Query([out, retval] BSTR* pbsQuery);HRESULT Query([in] BSTR bsQuery);

Parameters

RemarksThis property returns the query string that has been constructed using the other ISearchQuery2 methods.

Return value

ExampleThis 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, "");

[out, retval] BSTR* pbsQuery Pointer to a string (BSTR) that will contain the query held in this object.

[in, string] BSTR bsQuery String (BSTR) containing the query with which to initialize the object.

rvS_OK Success.

Page 541: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

541Search APIISearchQuery :: Clear

ISearchQuery :: ClearThis 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.

SyntaxHRESULT Clear([out, retval] BSTR* pbsQuery);

Parameters

RemarksClears out the string containing the query that has been constructed so far.

Return value

ExampleIn this example the previous query is stored in the string 'oldQuery'.

C#//save the query that is being cleared outstring oldQuery = query.Clear();

[out, retval] BSTR* pbsQuery A pointer to a string (BSTR) that contains the contents of the query string before it was cleared out.

rvS_OK Success.

Page 542: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

542 Search APIISearchQuery :: SetTerm

ISearchQuery :: SetTermThis 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.

SyntaxHRESULT SetTerm([in, string] const BSTR bsProp,

[in] VARIANT vVal, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters

RemarksIf the bsProp parameter is left empty, then all indexed properties are searched for the value. This is really only useful for string values.

bsProp can be a custom index property that has been added using the SimpleIndexMetadata API. This would be specified using the format:

propertySet.propertyName

If the custom index property is a member of the global property set, then the property set name is omitted.

The parameter lFlags must contain one value from “ESearchQueryFlags enumeration” on page 533. This value may be bitwise OR'd (C++ operator ‘|’) with one or more values from the extended values.

[in, string] const BSTR bsProp The name of the property to be searched for.

[in] VARIANT vVal VARIANT containing value for which for which to search. This can be a string, date or integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the terms added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string (BSTR) that contains the current value of the query string after this method has returned.

Page 543: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

543Search APIISearchQuery :: SetTerm

Return value

ExampleIn this example a query is constructed that will find all items where the subject contains the phrase 'some subject', and the number of attachments is 1. In this example the return value is not used.

C#//search for an item where the subject contains the phrase "some subject"query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase);//search for an item with 1 attachmentquery.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany);//now we AND the 2 terms so that both terms must be satisfied before returning a resultquery.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);

See also■ “ISearchQuery :: AddTerm” on page 544

■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

rvS_OK Success.

Page 544: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

544 Search APIISearchQuery :: AddTerm

ISearchQuery :: AddTermThis method is used to add a new term (property) to the query.

SyntaxHRESULT AddTerm([in, string] const BSTR bsProp,

[in] VARIANT vVal, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters

RemarksIf the bsProp parameter is left empty, than all indexed properties are searched for the value. This is really only useful for string values.

bsProp can be a custom index property that has been added using the SimpleIndexMetadata API. This would be specified using the format:

property_set_name.property_name

If the custom index property is a member of the global property set, then the property set name is omitted.

Table 8-1 AddTerm method parameters

Parameter Description

[in, string] const BSTR bsProp The name of the property in which to search for the value.

[in] VARIANT vVal VARIANT containing value for which to search. This can be a string, date or integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the terms added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the current value of the query string after this method has returned.

Page 545: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

545Search APIISearchQuery :: AddTerm

The parameter lFlags must contain one value from table “ESearchQueryFlags enumeration” on page 533, this value may be bitwise or'd (C++ operator ‘|’) with one or more values from the extended values.

Return value

ExampleIn this example a query is constructed that will find all items where the subject contains the phrase 'some subject' and the number of attachments is 1. In this example the return value is not used.

C#//search for an item where the subject contains the phrase "some subject"query.SetTerm("subj", "some subject", (int)ESearchQueryFlags.ESQphrase);//search for an item with 1 attachmentquery.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany);//now we AND the two terms so that both terms must be satisfied before returning a resultquery.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);

See also■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

■ “ISearchQuery :: SetTerm” on page 542

■ “ISearchQuery :: AddProperty” on page 552

rvS_OK Success.

Page 546: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

546 Search APIISearchQuery :: SetRange

ISearchQuery :: SetRangeThis 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.

SyntaxHRESULT SetRange([in, string] const BSTR bsProp,

[in] VARIANT vVal1, [in] VARIANT vVal2, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters

RemarksThis method can only be used with date or integer values. Currently date values are always treated as local system date/time values.

bsProp can be a custom index property that has been added using the SimpleIndexMetadata API. This would be specified using the format:

propertySet.propertyName

If the custom index property is a member of the global property set, then the property set name is omitted.

[in, string] const BSTR bsProp The name of the property in which to search for the value.

[in] VARIANT vVal1 The first value in the range. This can be date or integer.

[in] VARIANT vVal2 The last value in the range. This can be date or integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the current value of the query string after this method has returned.

Page 547: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

547Search APIISearchQuery :: SetRange

vVal1 and vVal2 must be the same type.

The parameter lFlags must contain one value from “ESearchQueryFlags enumeration” on page 533. Currently, however, none of the Search Query Flags has any effect on range searches.

Return value

ExampleThis 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 inclusiveDateTime 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 attachmentsquery.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) rangesquery. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);

See also■ “ISearchQuery :: AddRange” on page 548.

■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

rvS_OK Success.

Page 548: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

548 Search APIISearchQuery :: AddRange

ISearchQuery :: AddRangeThis method is used to add a date or numeric integer range to the query being built in the object.

SyntaxHRESULT AddRange([in, string] const BSTR bsProp,

[in] VARIANT vVal1, [in] VARIANT vVal2, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters

RemarksThis method can only be used with date/time or integer values.

Currently, date values are always treated as local system date/time values.

bsProp can be a custom index property that has been added using the SimpleIndexMetadata API. This would be specified using the format:

property_set_name.property_name

If the custom index property is a member of the global property set, then the property set name is omitted.

vVal1 and vVal2 must be the same type.

[in, string] const BSTR bsProp The name of the property in which to search for the value.

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

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

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the current value of the query string after this method has returned.

Page 549: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

549Search APIISearchQuery :: AddRange

The parameter lFlags must contain one value from “ESearchQueryFlags enumeration” on page 533. Currently, however, none of the Search Query Flags has any effect on range searches.

Return value

ExampleThis 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 inclusiveDateTime 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 attachmentsquery.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) rangesquery. AddOp((int)ESearchQueryOperators.ESQor, (int)ESearchOperatorScope.ESQdefault);

See also■ “ISearchQuery :: SetRange” on page 546.

■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

rvS_OK Success.

Page 550: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

550 Search APIISearchQuery :: SetProperty

ISearchQuery :: SetPropertyThis 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.

SyntaxHRESULT SetProperty([in, string] const BSTR bsPropSet,

[in, string] const BSTR bsProp, [in] VARIANT vVal, [in, defaultvalue(0)] const long lFlags, [out, retval] BSTR* pbsQuery);

Parameters

RemarksNote 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

[in, string] const BSTR bsPropSet Name of the property set.

[in, string] const BSTR bsProp The name of the custom property to search for.

[in] VARIANT vVal VARIANT containing value to search for.This can be a string, date or integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string containing the query as it stands after this method returns.

rvS_OK Success.

Page 551: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

551Search APIISearchQuery :: SetProperty

ExampleIt is assumed that a custom property "Type", belonging to the property set "Instrument", has been added to archived items.

Two queries are constructed in this sample; the first searches for all queries with the custom property Instrument.Type = 'Guitar. The second searches for all items where the retention category = 'Business'.

The two queries are combined to form one query that searches for all items where Instrument.Type is 'Guitar' and retention category is not 'Business'.

C#

//search for items with custom property value `Guitar'string qry1 = query.SetProperty("Instrument", "Type", "Guitar", (int)

ESearchQueryFlags.ESQexact);//search for items with a retention category of "Business"string qry2 = query.SetTerm("rcat", "Business", (int)(ESearchQueryFlags.ESQexact);//combine the 2 queries so that the result set contains items that contain `Guitar' in the custom property Instrument.Type and that have a retention category that is not `Business'query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot);

See also■ “ISearchQuery :: SetTerm” on page 542.

■ “ISearchQuery :: AddProperty” on page 552.

■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

Page 552: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

552 Search APIISearchQuery :: AddProperty

ISearchQuery :: AddPropertyThis method adds a custom property to the query being built in the object and which can be used for searching.

SyntaxHRESULT 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

RemarksThis 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

[in, string] const BSTR bsPropSet Name of the property set.

[in, string] const BSTR bsProp The name of the custom property to search for.

[in] VARIANT vVal VARIANT containing value for which forwhich to search. This can be a string, dateor integer.

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string containing the query as it stands after this method returns.

rvS_OK Success.

Page 553: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

553Search APIISearchQuery :: AddProperty

ExampleIn this example we use the return value which holds the current query. It is also assumed that a custom property "Type", belonging to the property set "Instrument", has been added to archived items as well as a custom property "Colour", belonging to the same property set.

The example builds two queries; the first searches for all items where Instrument.Colour is 'Red'. The second searches for items where Instrument.Type is 'Guitar'. The two queries are combined to form one, in order to search for all items where Instrument.Type is 'Guitar' and 'Instrument.Colur is 'Red'.

C#//search for items where custom property Instrument.Colour = "Red"string qry1 = query.SetProperty("Instrument", "Colour", "red",

(int)ESearchQueryFlags.ESQexact);//search for items with custom property Instrument.Type = `Guitar'string qry2 = query.AddProperty("Instrument", "Type", "Guitar", (int)(

ESearchQueryFlags.ESQexact);//combine the 2 queries so that the result set contains items that contain `Guitar' in the custom property Instrument.Type and "red" in Instrument.Colour"query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQand);

See also■ “ISearchQuery :: AddTerm” on page 544.

■ “ISearchQuery :: SetProperty” on page 550.

■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

Page 554: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

554 Search APIISearchQuery :: AddOp

ISearchQuery :: AddOpThis method is used to add an operator to the query in order to combine previously defined terms.

SyntaxHRESULT AddOp([in] const long lOp,

[in, defaultvalue(0)] const long lScope, [out, retval] BSTR* pbsQuery);

Parameters

RemarksThis method combines the previous x properties by using the operator defined in the first parameter, where x is the value given in the second parameter.

An example of an operator is 'AND' or 'OR'.

This method does not check the validity of the value passed to the first parameter, so an error will only be reported when Search is called.

This method can be called successively in order to build up the query.

Return value

[in] const long lOp The operator to use.

See “ESearchQueryOperators enumeration” on page 534.

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

See “ESearchOperatorScope enumeration” on page 534.

[out, retval] BSTR* pbsQuery Pointer to string that will contain the value of the query after this operator has been added.

rvS_OK Success.

Page 555: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

555Search APIISearchQuery :: AddOp

ExampleIn 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 attachmentquery.AddTerm("natc", 1, (int)ESearchQueryFlags.ESQany);//now we AND the 2 terms so that both terms must be satisfied before returning a resultquery.AddOp((int)ESearchQueryOperators.ESQand, (int) ESearchOperatorScope.ESQdefault);

Page 556: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

556 Search APIISearchQuery :: Combine

ISearchQuery :: CombineThis method clears the current query in the object and then adds queries from two other query objects. These are combined using the specified operator.

SyntaxHRESULT Combine([in, string] const BSTR bsQuery1,

[in, string] const BSTR bsQuery2, [in] const long lOp, [out, retval] BSTR* pbsQuery);

Parameters

RemarksThis 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

[in, string] const BSTR bsQuery1 First query to add.

[in, string] const BSTR bsQuery2 Second query to add.

[in] const long lOp The operator to use.

See “ESearchQueryOperators enumeration” on page 534.

[out, retval] BSTR* pbsQuery Pointer to a string that contains the query that results from this method.

rvS_OK Success.

Page 557: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

557Search APIISearchQuery :: Combine

ExampleIn this example we create two queries; the first searches for all items where the custom property Instrument.Type is 'Guitar', and the second searches for all items with a retention category of 'Business'. The return values hold the resultant queries. These are then combined to produce one query to search for all items where Instrument.Type is 'Guitar' and retention category is not 'Business'.

C#

//search for items with custom property value `Guitar' string qry1 = query.SetProperty("Instrument", "Type", "Guitar", (int)(

ESearchQueryFlags.ESQexact);//search for items with a retention category of "Business"string qry2 = query.SetTerm("rcat", "Business", (int)(ESearchQueryFlags.ESQexact);

//combine the 2 queries so that the result set contains items that contain `Guitar' in the custom property Instrument.Type and that have a retention category that is not `Business'query.Combine(qry1, qry2, (int)ESearchQueryOperators.ESQandnot);

Page 558: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

558 Search APIISearchQuery :: AddQuery

ISearchQuery :: AddQueryThis method is used to combine a query from another query object with the query in the current object, using the specified operator.

SyntaxHRESULT AddQuery([in, string] const BSTR bsQuery1,

[in] const long lOp, [out, retval] BSTR* pbsQuery);

Parameters

RemarksCombines 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

ExampleIn this example it is assumed there is already a populated ISearchQuery object, query2.

This example adds a new query string to this existing query.

[in, string] const BSTR bsQuery1 String containing the query to combine with the one in the current object.

[in] const long lOp The operator to use.

See “ESearchQueryOperators enumeration” on page 534.

[out, retval] BSTR* pbsQuery Pointer to a string that will contain the resulting query string.

rvS_OK Success.

Page 559: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

559Search APIISearchQuery :: AddQuery

C#string qry = query.SetTerm("cont", "-white blue.red",

(int)ESearchQueryFlags.ESQany);query2.AddQuery(qry, (int)ESearchQueryOperators.ESQand);

Page 560: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

560 Search APIISearchQuery2 :: SetPropertyRange

ISearchQuery2 :: SetPropertyRangeThis method is used to add a date or integer range to a query that specifies a custom index property. The method deletes any queries in the current object, resets it, and adds the specified information as part of a new query.

Custom index properties can be added to index entries using the SimpleIndexMetadata API.

“SimpleIndexMetadata object” on page 277.

SyntaxHRESULT 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

RemarksThis method can only be used with date or integer values.

bsProp can be a custom index property that has been added using the SimpleIndexMetadata API. bsPropSet specifies the property set.

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

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

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that will contain the query string formed by this method.

Page 561: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

561Search APIISearchQuery2 :: SetPropertyRange

vVal1 and vVal2 must be the same type.

The parameter lFlags must contain one value from table “ESearchQueryFlags enumeration” on page 533. Currently, however, none of the Search Query Flags has any effect on range searches.

Note that SetRange can also be used with custom properties, using the propertySet.propertyName format.

Return value

ExampleIn 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 5query.SetPropertyRange("CustomTags", "Relevance", 0, 5,

(int)ESearchQueryFlags.ESQany);

See also■ “Adding custom index metadata” on page 55

■ “ISearchQuery :: SetRange” on page 546

■ “ISearchQuery :: AddRange” on page 548

■ “ISearchQuery2 :: AddPropertyRange” on page 562

■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

rvS_OK Success.

Page 562: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

562 Search APIISearchQuery2 :: AddPropertyRange

ISearchQuery2 :: AddPropertyRangeThis method is used to add a date or integer range to a query that specifies a custom index property.

Custom index properties can be added to index entries using the SimpleIndexMetadata API.

“SimpleIndexMetadata object” on page 277.

SyntaxHRESULT 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

RemarksThis method can only be used with date or integer values.

bsProp can be a custom index property that has been added using the SimpleIndexMetadata API. bsPropSet specifies the property set.

[in, string] const BSTR bsPropSet String containing the name of the property set.

[in, string] const BSTR bsProp String containing the property name.

[in] VARIANT vVal1 VARIANT specifying the first value in the range.

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

[in, defaultvalue(0)] const long lFlags Search Query Flags that define how to process the range added to the search query.

See “ESearchQueryFlags enumeration” on page 533.

[out, retval] BSTR* pbsQuery Pointer to a string that will contain the query string formed by this method.

Page 563: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

563Search APIISearchQuery2 :: AddPropertyRange

vVal1 and vVal2 must be the same type.

The parameter lFlags must contain one value from table “ESearchQueryFlags enumeration” on page 533. Currently, however, none of the Search Query Flags has any effect on range searches.

Note that AddRange can also be used with custom properties, using the propertySet.propertyName format.

Return value

ExampleIn 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 5query.AddPropertyRange("CustomTags", "Relevance", 0, 5,

(int)ESearchQueryFlags.ESQany);

See also■ “Adding custom index metadata” on page 55

■ “ISearchQuery :: SetRange” on page 546

■ “ISearchQuery :: AddRange” on page 548

■ “ISearchQuery2 :: SetPropertyRange” on page 560

■ “System properties” on page 664.

■ “SimpleIndexMetadata object” on page 277.

rvS_OK Success.

Page 564: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

564 Search APIIndexSearch object

IndexSearch objectIndexSearch object implements the following interface:

■ IIndexSearch2

IIndexSearch2 provides properties and methods that can be used to enable the user to search an archive using a query that has been built using the methods of ISearchQuery2.

The output from a search is a pointer to an ISearchResults2 interface, the implementation of which contains a collection of ISearchResult2 pointers.

Syntaxinterface IIndexSearch2 : IDispatch

Member summary

Property Read/Write Description

IndexVolumeSets Read only Returns a collection of Index Volume Sets used by the currently selected archive.

Options Read/Write Sets or retrieves the current search options.

SortBy Read/Write Gets or sets the current properties used to order the returned search results. (None or one index property).

ResultsPropertySet Read/Write Gets or sets a predefined list of properties whose values are to be returned as part of the result set.

See “EPropertySets enumeration” on page 535.

See “Remarks” on page 566.

AdditionalResultsProperties Read/Write A space separated list of properties returned in the search results in addition to those in the selected results property set.

Page 565: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

565Search APIIndexSearch object

Timeout Read/Write Gets or sets the timeout period, in seconds, applied to federated search requests (that is, searches across multiple index volume sets).

ArchiveEntryId Read only Gets the Id of the currently selected archive.

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

HasFolders Read only Returns true if the currently selected archive contains folders.

IndexVolumeSetIdentity Read only Gets the identity of the currently selected index volume set.

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

IndexVolumeSetCount Read only Gets the number of index volume sets for the currently selected archive.

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

MaxSearchResultsPerVolumeSet Read/Write For federated searches only, gets or sets the current value of the maximum number of results to be returned per volume set. Default is 1000.

Method Description

SelectArchive Sets the Id of the archive to be searched.

Property Read/Write Description

Page 566: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

566 Search APIIndexSearch object

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

ListIndexVolumeSets Returns as an XML document the index volume set collection for the selected archive.

SelectIndexVolumeSet Set the Id of the archive's index volume set to search. If an index volume set is not selected, and the number of index volume sets is less than, or equal to, MaxSearchIndexVolumeSets, then a federated search is automatically performed across the index volume sets. If the number of index volume sets is greater than MaxSearchIndexVolumeSets, then the index volume set to search must be selected.

SelectIndexVolume This property should not be used.As Enterprise Vault only supports one volume per volume set, use SelectIndexVolumeSet to select a specific index volume to search.

See “Remarks” on page 566.

Search Search the selected archive index or selected IndexVolumeSet.

SearchToXML Search the selected archive index or selected IndexVolumeSet, and return the results as XML.

AddAdditionalResultsProperty Adds a single property to the AdditionalResultsProperties list.

This should be used in preference to ResultsPropertySet.

AddAdditionalResultsCustomProperty Adds a single custom property to the AdditionalResultsProperties list.

Reset Reset the object properties to their default values.

Method Description

Page 567: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

567Search APIIndexSearch object

IIndexSearch2 provides a method that returns a collection of index volume sets. This collection is accessed by methods and properties of the returned IIndexVolumeSet pointer.

If the number index volume sets is greater than the number set by MaxSearchIndexVolumeSets (5 is the default), then it is necessary to specify the archive Id and also the index volume sets to search, otherwise an error is returned, rvINDEXING_E_TOO_MANY_VOLUMES.

Currently, the index volume set is limited to one index volume. However, in a future release, index volume sets may contain more than one index volume. To prevent any confusion, all new applications should use methods and properties that specify index volume sets, as errors could occur if those that refer to index volumes (such as, IIndexSearch2 :: IndexVolumeIdentity) are used.

ExampleThe object, 'search', constructed in this example will be used in the most of the subsequent examples. It is shown here as a private class data member.

C#public class SampleSearchClass{

private IIndexSearch2 search = (IIndexSearch2) new IndexSearch2();

//rest of the class

See also■ “IndexVolumeSets object” on page 605

■ “IndexVolumeSet object” on page 615

Page 568: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

568 Search APIIIndexSearch2 :: IndexVolumeSets

IIndexSearch2 :: IndexVolumeSetsThis 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.

SyntaxHRESULT IndexVolumeSets([out,retval] IUnknown**

volumeSetsCollection);

Parameters

RemarksThis property must not be used before SelectArchive has been called.

The returned data should not be persisted, as the collection of index volume sets associated with an archive may change over time. Also when indexes are rebuilt the set of index volumes will change.

See “IndexVolumeSets object” on page 605 for details of index volume sets.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;foreach (IIndexVolumeSet volSet in volSets){

[out,retval] IUnknown** volumeSetsCollection Pointer to an IUnknown pointer that can be QI'd (or cast) to obtain an IIndexVolumeSets pointer.

rvS_OK Success.

rvE_POINTER An invalid pointer has been received.

rvINDEXING_W_ARCHIVE_NOT_SET The archive to search has not been set.

Page 569: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

569Search APIIIndexSearch2 :: IndexVolumeSets

search.SelectIndexVolumeSet(volSet.Identity);DoSearch(search);

}

Page 570: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

570 Search APIIIndexSearch2 :: Options

IIndexSearch2 :: OptionsThis property sets or returns search option flags that define the granularity of search results.

The property is read/write.

SyntaxHRESULT Options([in] long options,

[out,retval] long* options);

Parameters

RemarksBoth messages and their attachments are searched, but the granularity of search results (Option) defines whether attachments are returned in search results or only the top-level items.

See “EOptionsFlags enumeration” on page 535.

Return value

Example

C#[in]search.Options = (int)EOptionsFlags.roItemGranularity;[out]EOptionsFlags eof = (EOptionsFlags )search.Options;

[in] long options EOptionsFlags value defining required granularity of search results.

“EOptionsFlags enumeration” on page 535.

[out,retval] long* options Pointer to a long integer that will contain the current value.

rvS_OK Success.

rvE_POINTER An invalid pointer has been received.

Page 571: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

571Search APIIIndexSearch2 :: Options

if (eof == EOptionsFlags.roAttachmentGranularity){ //do something}else //do something else

Page 572: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

572 Search APIIIndexSearch2 :: SortBy

IIndexSearch2 :: SortByThis property is used to order the returned search results.

The property is read/write.

SyntaxHRESULT SortBy([in] BSTR sortProperties,

[out,retval] BSTR* sortProperties);

Parameters

RemarkssortProperties 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

ExampleThis example shows how to sort by archived date, in descending order.

C#[in]//sort by archived date descendingsearch.SortBy = "-" + "adat";[out]string sortBy = search.SortBy;

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

rvS_OK Success.

rvE_POINTER The pointer passed in to receive the current value is invalid.

Page 573: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

573Search APIIIndexSearch2 :: ResultsPropertySet

IIndexSearch2 :: ResultsPropertySetThis 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.

SyntaxHRESULT ResultsPropertySet([in] long propertySet,

[out,retval] long* propertySet);

Parameters

Remarks“EPropertySets enumeration” on page 535 lists the values for the predefined property sets.

As the predefined property sets may change in future releases, we strongly recommend that you set this property to psEmpty, and use the AdditionalResultsProperties property and/or AddAdditionalResultsProperty and AddAdditionalResultsCustomProperty to set the required properties to be found in the result set.

See “EPropertySets enumeration” on page 535.

Return value

[in] long propertySet Long integer containing the EPropertySets value to be set.

See “EPropertySets enumeration” on page 535.

[out,retval] long* propertySet Pointer to a long integer that will receive the current value.

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.

Page 574: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

574 Search APIIIndexSearch2 :: ResultsPropertySet

ExampleAs this property is no longer the recommended way of setting the returned properties, it is set to ‘empty'.

C#[in]search.ResultPropertySet = (int)EPropertySets.psEmpty;[out]if (search.ResultPropertySet != 0){

search.ResultPropertySet = 0; // (psEmpty)}

See also■ “IIndexSearch2 :: AdditionalResultsProperties” on page 575

■ “IIndexSearch2 :: AddAdditionalResultsProperty” on page 601

■ “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 602.

Page 575: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

575Search APIIIndexSearch2 :: AdditionalResultsProperties

IIndexSearch2 :: AdditionalResultsPropertiesThis property is the recommended way to define the properties returned in search results.

The property is read/write.

SyntaxHRESULT AdditionalResultsProperties([in] BSTR propertiesList);HRESULT AdditionalResultsProperties([out,retval] BSTR* propertiesList);

Parameters

RemarksThe properties added must be in the format of a space delimited list.

Properties you define using this property should be in addition to those found in the predefined property sets. It is recommended that the empty ResultPropertySet is selected.

See “EPropertySets enumeration” on page 535.

Return value

ExampleNote that as IIndexSearch2::ResultPropertySet is no longer a preferred method, it is set 'empty' as a precaution.

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

rvS_OK Success.

rvE_POINTER The string pointer passed in to receive the current value is invalid.

Page 576: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

576 Search APIIIndexSearch2 :: AdditionalResultsProperties

C#[in]search.ResultPropertySet = (int)EPropertySets.psEmpty; //set emptysearch.AdditionalResultsProperties = "ssid adat natc";[out]string props = search.AdditionalResultsProperties;if (props.Contains("ssid")){ //do something

See also■ “IIndexSearch2 :: AddAdditionalResultsProperty” on page 601

■ “IIndexSearch2 :: AddAdditionalResultsCustomProperty” on page 602

■ “IIndexSearch2 :: ResultsPropertySet” on page 573

Page 577: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

577Search APIIIndexSearch2 :: Timeout

IIndexSearch2 :: TimeoutThis property defines the timeout period applied to federated search requests.

The property is read/write.

SyntaxHRESULT Timeout([in] long seconds,

[out,retval] long* seconds);

Parameters

RemarksDefines the period in seconds before a search request times out - the default value is 60 seconds.

This property applies to federated searches only.

Return value

Example

C#[in][out]if (search.Timeout < 60){ search.Timeout = 60;}

[in] long seconds Long integer containing number of seconds to wait beforethe search times out. The default value is 60 seconds.

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

Page 578: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

578 Search APIIIndexSearch2 :: ArchiveEntryId

IIndexSearch2 :: ArchiveEntryIdThis property returns the ID of the archive that is currently selected for searching.

The property is read only.

SyntaxHRESULT ArchiveEntryId([out,retval] BSTR* value)

Parameters

RemarksThis method will only return a valid Id after SelectArchive has been called.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");//do somethingstring aeid = search.ArchiveEntryId;

[out,retval] BSTR* value Pointer to a string that will receive the current 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.

Page 579: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

579Search APIIIndexSearch2 :: ArchiveName

IIndexSearch2 :: ArchiveNameThis property returns the name of the archive that is currently selected for searching.

The property is read only.

SyntaxHRESULT ArchiveName([out,retval] BSTR* value);

Parameters

RemarksThis 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

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");//display the archive name in a textbox.textBoxArchId.Text = search.ArchiveName;

[out,retval] BSTR* value Pointer to a string that will contain the current 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.

Page 580: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

580 Search APIIIndexSearch2 :: HasFolders

IIndexSearch2 :: HasFoldersThis property indicates whether the currently selected archive contains a folder structure.

The property is read only.

SyntaxHRESULT HasFolders([out,retval] VARIANT_BOOL* value);

Parameters

RemarksThis method will only return a valid result after SelectArchive has been called.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");//do somethingif (search.HasFolders == true){ //do something

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive the current value.

rvS_OK Success.

rvE_POINTER Value is an invalid pointer.

rvS_FALSE The archive has not been selected.

Page 581: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

581Search APIIIndexSearch2 :: IndexVolumeSetIdentity

IIndexSearch2 :: IndexVolumeSetIdentityThis property identifies the volume set of the index volume to search.

The property is read only.

SyntaxHRESULT IndexVolumeSetIdentity([out,retval] long* value);

Parameters

RemarksThis 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

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");//do somethinglong id = search.IndexVolumeSetIdentity;if (id == -1) MessageBox.Show("This archive has multiple Index Volume Sets -

please select one", "Multiple Index Volume Sets", MB_OK);

[out,retval] long* value Pointer to a long that will receive the current 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.

Page 582: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

582 Search APIIIndexSearch2 :: IndexVolumeIdentity

IIndexSearch2 :: IndexVolumeIdentityThis property should not be used: it is currently available for Enterprise Vault internal purposes only.

The property is read only.

SyntaxHRESULT IndexVolumeIdentity([out,retval] long* value);

Parameters

RemarksThis property should not be used.

This property returns the IndexVolumeIdentity as selected by the search application.

See “Remarks” on page 566.

Return value

[out,retval] long* value Pointer to a long integer that will hold the current 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.

Page 583: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

583Search APIIIndexSearch2 :: IndexVolumeSetCount

IIndexSearch2 :: IndexVolumeSetCountThis property returns the number of index volume sets in the archive’s index.

The property is read only.

SyntaxHRESULT IndexVolumeSetCount([out,retval] long* value);

Parameters

RemarksThis property should not be used before SelectArchive has been called.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");long count = search.IndexVolumeSetCount;//want to do a federated search depending on number of Index Volume setsif (count <= 10){

//do federated searchsearch.MaxSearchIndexVolumeSets = count;//carry on with search

}else{ //do non-federated search}

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

Page 584: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

584 Search APIIIndexSearch2 :: MaxSearchIndexVolumeSets

IIndexSearch2 :: MaxSearchIndexVolumeSetsThis property specifies the maximum number of index volume sets that can be searched by a federated search (that is, a search across multiple index volume sets).

The property is read/write.

SyntaxHRESULT MaxSearchIndexVolumeSets([out, retval] LONG* pVal,

[in] LONG newVal);

Parameters

RemarksThis property should not be used before SelectArchive has been called.

Default value is 5. A search that spans multiple index volume sets is called a federated search.

The default value has been selected to provide a reasonable performance and response times for federated searches. Increasing this value will extend response times and also consume additional memory and CPU resource in the client application when correlating the search results from the additional index volume sets’ searches.

Return value

[out, retval] LONG* pVal Pointer to a long integer that will receive the maximum number of index volume sets that can be searched. The default is 5.

[in] LONG newVal Long integer containing the new value to set.

rvS_OK

rvE_INVALIDARG The new value being set is less than 1.

rvE_POINTER The long pointer passed in to receive the current value is invalid.

Page 585: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

585Search APIIIndexSearch2 :: MaxSearchIndexVolumeSets

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");long count = search.IndexVolumeSetCount;//want to do a federated search depending on number of Index Volume setsif (count <= 10){

//do federated searchsearch.MaxSearchIndexVolumeSets = count;//carry on with search

}else{

//do non-federated search

Page 586: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

586 Search APIIIndexSearch2 :: MaxSearchResultsPerVolumeSet

IIndexSearch2 :: MaxSearchResultsPerVolumeSetThis property indicates the maximum number of search results that can be returned per volume set by a federated search (that is, a search across multiple index volume sets).

The property is read/write.

SyntaxHRESULT MaxSearchResultsPerVolumeSet([out, retval] LONG* pVal,

[in] LONG newVal);

Parameters

RemarksThis property should not be used before SelectArchive has been called.

In a federated search, results returned from each volume set are processed and merged. This property indicates the maximum number of search results per volume set that can be processed and merged. The default is 1000 search results per volume set.

The default value has been selected to provide a reasonable performance and response times for federated searches. Increasing this value will extend response times and will also consume additional memory and CPU resource in the client application in order to correlate the increased number of search results.

Return value

[out, retval] LONG* pVal Pointer to a long integer that will receive the current value.

[in] LONG newVal Long integer that sets the new value required.

rvS_OK

rvE_INVALIDARG The new value being set is less than 1.

rvE_POINTER The long pointer passed in to receive the current value is invalid.

Page 587: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

587Search APIIIndexSearch2 :: MaxSearchResultsPerVolumeSet

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");long count = search.IndexVolumeSetCount;//want to do a federated search depending on number of Index Volume setsif (count <= 10){

//do federated searchsearch.MaxSearchIndexVolumeSets = count;search.MaxsearchResultsPerVolumeSet = 500;//carry on with search

}else{

//do non-federated search

Page 588: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

588 Search APIIIndexSearch2 :: SelectArchive

.

IIndexSearch2 :: SelectArchiveThis method is used to select an archive to search.

SyntaxHRESULT SelectArchive([in]BSTR archiveEID);

Parameters

RemarksThe SelectArchive method specifies the archive to search in subsequent calls to Search or SearchToXML. The archive must be selected before attempting to list index volume sets associated with the index, or search the index.

See “Performing a search” on page 524 for ways of finding out the ID of an archive.

Return value

Example

C#Assume there is a populated IArchives object, 'archives'.foreach (IArchive archive in archives){ search.SelectArchive(archive.Id);

[in]BSTR archiveEID String containing the Id of the archive to search.

rvS_OK Success.

rvE_INVALIDARG Either a zero length string has been passed orthe archive entry specified could not be found

rvINDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_INDEXDISABLED Indexing has been disabled for this archive; the archive status is INDEX_ITEMS_DEFERRED_INDEFINITELY.

Page 589: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

589Search APIIIndexSearch2 :: SelectArchive

DoSearch(search, 500);}

See also■ “IIndexSearch2 :: Search” on page 595

■ “IIndexSearch2 :: SearchToXML” on page 598

Page 590: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

590 Search APIIIndexSearch2 :: ListIndexVolumeSets

IIndexSearch2 :: ListIndexVolumeSetsThis method is used to list the index volume set collection for the selected archive as an XML document.

SyntaxHRESULT ListIndexVolumeSets([in] BSTR processingInstruction,

[out,retval] BSTR* volumeSetsList);

Parameters

RemarksAn archive must have been selected using SelectArchive.

This method is an alternative to using the IndexVolumeSets property. IndexVolumeSets returns a pointer to an enumerated collection of IIndexVolumeSet interface pointers, which can be accessed using the properties and methods of the returned interface pointer.

Return value

[in] BSTR processingInstruction String containing an optional parameter that enables the caller to specify an XML processing instruction. This is added to the XML following the XML declaration. For example, an XSL style sheet reference can be specified with the following string:

xml-stylesheet href="indexvolumesets.xsl" type="text/xsl"

(XML processing instruction delimiters are added by the method).

[out,retval] BSTR* volumeSetsList Pointer to a string that will receive the XML document.

rvS_OK Success.

rvE_POINTER The parameter volumeSetList is a NULL pointer.

rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set.

Page 591: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

591Search APIIIndexSearch2 :: ListIndexVolumeSets

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");string volSetsXML = search.ListIndexVolumeSets("xml-stylesheet

href='indexvolumesets.xsl' type='text/xsl'");//do something with the XML

The following gives an example of the XML returned by the ListIndexVolumeSets method.

For the last index volume set, all elements except FirstItemSequenceNumber are optional, since it may represent a new index volume that has not yet been committed to disk.<?xml version="1.0" encoding="utf-16" ?><IndexVolumeSets xmlns="urn:kvsinc-com:EnterpriseVault"

ArchiveEntryId="12234E1CE26421C45A096DD3CA06527071110000evsvr"ArchiveName="John Smith"HasFolders="True">

<IndexVolumeSet Identity="20"><FirstItemSequenceNumber>1</FirstItemSequenceNumber><OldestArchivedDate>2002-03-13T12:50:38Z</OldestArchivedDate>

<YoungestArchivedDate>2004-04-18T06:49:44Z</YoungestArchivedDate><OldestItemDate>1998-03-26T05:34:02Z</OldestItemDate><YoungestItemDate>2004-03-02T22:22:23Z</YoungestItemDate>

</IndexVolumeSet><IndexVolumeSet Identity="29">

<FirstItemSequenceNumber>16666344</FirstItemSequenceNumber><OldestArchivedDate>2004-04-18T06:49:50Z</OldestArchivedDate>

<YoungestArchivedDate>2004-04-25T07:02:44Z</YoungestArchivedDate><OldestItemDate>2004-03-12T20:12:03Z</OldestItemDate><YoungestItemDate>2004-03-13T22:06:16Z</YoungestItemDate>

</IndexVolumeSet></IndexVolumeSets>

See also■ “IIndexSearch2 :: IndexVolumeSets” on page 568

■ “IndexVolumeSets object” on page 605

■ “IndexVolumeSet object” on page 615

Page 592: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

592 Search APIIIndexSearch2 :: SelectIndexVolumeSet

IIndexSearch2 :: SelectIndexVolumeSetThis method selects an index volume set when searching an index with multiple index volume sets.

SyntaxHRESULT SelectIndexVolumeSet([in] long volumeSetIdentity);

Parameters

RemarksAn archive must have been selected using SelectArchive.

For an index with a single index volume set, that index volume set is selected by default.

Unless this property is set to specify an index volume set to search, then a feder-ated search will be carried out across all index volume sets in the archive. How-ever, if the number of index volume sets exceeds the number set by MaxSearchIndexVolumeSets (default is 5), this property must be set to deter-mine which index volume set to search, otherwise the Search API will return an error, rvINDEXING_E_TOO_MANY_VOLUMES.Index volume set Ids can be obtained using the ListIndexVolumeSets method.

Return value

[in] long volumeSetIdentity Long integer containing the Id of the index volume set.

rvS_OK Success.

rvE_INVALIDARG

rvINDEXING_W_ARCHIVE_NOT_SET The archive Id has not been set.

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET The volume set specified does not exist.

rvINDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_UNABLE_FAILED_VOLUME A volume in the set is known to have failed - no reason specified.

Page 593: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

593Search APIIIndexSearch2 :: SelectIndexVolumeSet

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");//set up the search ISearchResults2 results = null;if (search.IndexVolumeSetCount > search.MaxSearchIndexVolumeSets){ IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets; foreach (IIndexVolumeSet volSet in volSets) { search.SelectIndexVolumeSet(volSet.Identity); //do the search etc. results = (ISearchResults2)search.Search(query.Query, 1, 100, ""); }}else results = (ISearchResults2)search.Search(query.Query, 1, 100, "");

rvINDEXING_E_UNABLE_OFFLINE_VOLUME A volume in the set is known to be offline.

Page 594: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

594 Search APIIIndexSearch2 :: SelectIndexVolume

IIndexSearch2 :: SelectIndexVolumeThis method is used to select a specific index volume of the archive to search.

SyntaxHRESULT SelectIndexVolume([in] long volumeIdentity);

Parameters

RemarksThis method should not be used. An Index Volume Set is considered the smallest element of an archive's index. The ability to select individual index volumes may be removed in a future release.

See “Remarks” on page 566.

Return value

[in] long volumeIdentity

rvS_OK Success.

rvE_INVALIDARG An unexpected error has occurred.

rvINDEXING_W_UNKNOWN_INDEX_VOLUME

rvINDEXING_W_ARCHIVE_NOT_SET

rvINDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_UNABLE_FAILED_VOLUME

rvINDEXING_E_UNABLE_OFFLINE_VOLUME

Page 595: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

595Search APIIIndexSearch2 :: Search

IIndexSearch2 :: SearchThis method submits the search request and returns a search results object.

See “SearchResults object” on page 627.

SyntaxHRESULT Search([in] BSTR bsQuery,

[in] long startResult, [in] long maximumResults,[in] BSTR reserved, [out, retval] IUnknown** resultsSet);

Parameters

RemarksAn empty query causes a full wildcard search, which matches all entries in the index. As maximum results will probably be exceeded, it is unlikely to return all the items in the index.

To ensure a well formed query is passed to this method, obtain an ISearchQuery2 interface pointer and construct a query using the properties and methods of this interface. See “SearchQuery object” on page 537.Each search starts a new search in the Indexing server.

The startResult and maximumResults arguments enable paging through search results.

[in] BSTR bsQuery String containing the query. This is normally the Query property of a SearchQuery object.

[in] long startResult Long integer containing the number of the first result. This can be 1 up to the total number of possible results.

[in] long maximumResults Long integer containing the maximum number of results to return.

[in] BSTR reserved This parameter must be "".

[out, retval] IUnknown** resultsSet Pointer to an IUnknown pointer. On return, the resulting IUnknown pointer can be QI'd(or cast) to obtain the required ISearchResults2 pointer.

Page 596: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

596 Search APIIIndexSearch2 :: Search

Results are numbered, in order, after sorting. Search results are ordered as follows:

■ Using the index property specified with the SortBy property, if any.

■ Otherwise, for those terms where the ESQRank flag was specified in the search term, by relevance to the words used in the search query.

See “ESearchQueryFlags enumeration” on page 533.

■ Otherwise, in order of addition to the index.

See “Performing a search” on page 524 for more information and recommendations for performing searches.

Return value

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed is the fourth parameter is invalid.

rvE_ACCESSDENIED

rvE_NOINTERFACE

rvE_SERVER_UNAVAILABLE

rvINDEXING_SERVER_STOPPING

rvINDEXING_E_SERVICE_STOPPING

rvINDEXING_E_ARCHIVE_NOT_SET

INDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_ARCHIVE_BEING_DELETED

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET

rvINDEXING_W_UNKNOWN_INDEX_VOLUME The selected index volume is not known.

rvINDEXING_W_UNABLE_FAILED_VOLUME

rvINDEXING_E_UNABLE_OFFLINE_VOLUME

rvINDEXING_W_SEARCH_WOULD_BLOCK

rvINDEXING_W_SEARCH_TIMEDOUT

Page 597: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

597Search APIIIndexSearch2 :: Search

ExampleIn this example it is assumed that an ISearchQuery2 object, ‘query', has been created and populated.

C#//select the archive and set up the search query etc//return a results set that starts from the first item found up to a total of 100 items.ISearchResults2 results = (ISearchResults2)search(query.Query, 1,

100, "");

Note the fourth parameter must be "".

See also■ “SearchQuery object” on page 537

■ “ESearchQueryFlags enumeration” on page 533

rvINDEXING_E_TOO_MANY_RESULTS

rvINDEXING_E_TOO_MANY_VOLUMES

rvINDEXING_E_INVALID_QUERY

rvINDEXING_E_ILLEGAL_WILDCARD_QUERY

rvINDEXING_E_FAILED_SEARCH_REQUEST

rvINDEXING_E_INDEX_SEARCH_FAILED

Page 598: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

598 Search APIIIndexSearch2 :: SearchToXML

IIndexSearch2 :: SearchToXMLThis method is used to search the selected index volume set or index volume and return the results as XML. This method is similar to Search, but it returns XML not an interface pointer.

SyntaxHRESULT SearchToXML([in] BSTR bsQuery,

[in] long startResult, [in] long maximumResults,[in] BSTR reserved, [in] BSTR processingInstruction, [in] long xmlFormatOptions,[out,retval] VARIANT* xmlResults);

Parameters

RemarksEXMLResultsFormatOptions enumerates the XML format option values. Currently there is only the following default value:xoNone = 0x00000000

[in] BSTR bsQuery String containing the query, this is normally the Query property of a SearchQuery object.

[in] long startResult Long integer containing the number of the first result. This can be 1 up to the total number of possible results.

[in] long maximumResults Long integer containing the maximum number of results to return.

[in] BSTR reserved This parameter must be "".

[in] BSTR processingInstruction String containing an XML processing instruction which will be inserted into the returned XML. For example, xml-stylesheet type="test/xsl" href="results.xsl"

[in] long xmlFormatOptions Long integer containing a flag from the EXMLResultsFormatOptions. Currently the only available value is 0.

[out,retval] VARIANT* xmlResults Pointer to a VARIANT containing the search results.

Page 599: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

599Search APIIIndexSearch2 :: SearchToXML

An empty query causes a full wildcard search, which matches all entries in the index. As maximum results will probably be exceeded, it is unlikely to return all the items in the index.

To ensure a well formed query is passed to this method, obtain an ISearchQuery2 interface pointer and construct a query using the properties and methods of this interface. See “SearchQuery object” on page 537.Each search starts a new search in the Indexing server.

The startResults and maximumResults arguments enable paging through search results.

Results are numbered, in order, after sorting. Search results are ordered as follows:

■ Using the index property specified with the SortBy property, if any.

■ Otherwise, for those terms where the ESQRank flag was specified in the search term, by relevance to the words used in the search query.

See “ESearchQueryFlags enumeration” on page 533.

■ Otherwise, in order of addition to the index.

See “Performing a search” on page 524 for more information and recommendations for performing searches.

Return value

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed is the fifth parameter is invalid.

rvE_ACCESSDENIED

rvE_NOINTERFACE

rvE_SERVER_UNAVAILABLE

rvINDEXING_SERVER_STOPPING

rvINDEXING_E_SERVICE_STOPPING

rvINDEXING_E_ARCHIVE_NOT_SET

INDEXING_W_CANT_ACCESS_DIRECTORY

rvINDEXING_E_ARCHIVE_NOT_FOUND

rvINDEXING_W_ARCHIVE_BEING_DELETED

Page 600: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

600 Search APIIIndexSearch2 :: SearchToXML

ExampleIn this example it is assumed that an ISearchQuery2 object, ’query', has been created and populated.

C#//select the archive and set up the search query etcbyte[] res = (byte[])search.SearchToXML(query.Query, 1, 100, "", "", 0);

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET

rvINDEXING_W_UNKNOWN_INDEX_VOLUME

rvINDEXING_W_UNABLE_FAILED_VOLUME

rvINDEXING_E_UNABLE_OFFLINE_VOLUME

rvINDEXING_W_SEARCH_WOULD_BLOCK

rvINDEXING_W_SEARCH_TIMEDOUT

rvINDEXING_E_TOO_MANY_RESULTS

rvINDEXING_E_TOO_MANY_VOLUMES

rvINDEXING_E_INVALID_QUERY

rvINDEXING_E_ILLEGAL_WILDCARD_QUERY

rvINDEXING_E_FAILED_SEARCH_REQUEST

rvINDEXING_E_INDEX_SEARCH_FAILED

Page 601: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

601Search APIIIndexSearch2 :: AddAdditionalResultsProperty

IIndexSearch2 :: AddAdditionalResultsPropertyThis method is used to add a single property to the AdditionalResultsProperties list. Using the AdditionalResultsProperty list is now the preferred way of specifying properties required in the results set.

SyntaxHRESULT AddAdditionalResultsProperty([in] BSTR propertyName);

Parameters

RemarksIn conjunction with AdditionalResultsProperties, this is now the preferred way to set up a list of properties to be returned. A custom property can be specified using the propertySet.propertyName format.

Return value

Example

C#search.AddAdditionalResultsProperty ("natc");

See also■ “IIndexSearch2 :: AdditionalResultsProperties” on page 575

[in] BSTR propertyName String containing the property to add to the list of properties returned in results.

rvS_OK Success.

rvE_POINTER

rvE_INVALIDARG A property name has not been specified

Page 602: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

602 Search APIIIndexSearch2 :: AddAdditionalResultsCustomProperty

IIndexSearch2 :: AddAdditionalResultsCustomProperty

This method is used to add a single custom property to the AdditionalResultsProperties list.

SyntaxHRESULT AddAdditionalResultsCustomProperty([in] BSTR propertySet,

[in] BSTR propertyName);

Parameters

RemarksIf the property is in the global property set, then the propertySet parameter should be set to NULL.

Custom properties can be added at the time of storage using the ISimpleIndexMetaData interface.

Return value

Example

C#search.AddAdditionalResultsCustomProperty("custpropset", "custpropname");

[in] BSTR propertySet String containing the name of the property set.

[in] BSTR propertyName String containing the name of the property.

rvS_OK Success.

rvE_POINTER A property name has not been specified.

rvE_INVALIDARG A property name has not been specified.

Page 603: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

603Search APIIIndexSearch2 :: AddAdditionalResultsCustomProperty

See also■ “IIndexSearch2 :: AdditionalResultsProperties” on page 575

■ “SimpleIndexMetadata object” on page 277

Page 604: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

604 Search APIIIndexSearch2 :: Reset

IIndexSearch2 :: ResetThis method is used to reset the object properties to their default values.

SyntaxHRESULT Reset();

RemarksThis method is used to reset the object properties to their default values.

Return value

Example

C#private void resetButton_Click(object sender, EventArgs e){ //reset button pressed so reset all object properties to default search.Reset();}

rvS_OK Success.

Page 605: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

605Search APIIndexVolumeSets object

IndexVolumeSets objectThis object implements the following interface:

■ IIndexVolumeSets

This interface provides a set of properties than can used to manage a collection of index volume sets.

Syntaxinterface IIndexVolumeSets : IDispatch

Member summary

RemarksAn index volume set comprises a sequence of index volumes; the order of index volumes is defined by the value of FirstItemSequenceNumber. Thus each index volume set contains all items archived between a start and end date defined by OldestArchivedDate and YoungestArchivedDate properties of the first and last index volume respectively.

The volume sets can be enumerated either using the Item property of IIndexVolumeSets, or using the enumerator returned by _NewEnum.

This interface pointer is returned by a call to the ListIndexVolumeSets method of IIndexSearch2.

Property Description

ArchiveEntryId The archive Id of the archive to which the index volume set collection belongs.

ArchiveName The name of the archive.

HasFolders Whether the archive contains a folder structure.

Count The number of index volume sets in the collection.

_NewEnum Returns an enumerator object for the collection of Index Volume Set objects or an Index Volume Set collection.

Item Returns an Index Volume Set object using a 1-based index of the collection.

Page 606: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

606 Search APIIndexVolumeSets object

ExampleNote that IIndexSearch2::SelectArchive must be called before using IIndexSearch2::IndexVolumeSets.

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;

See also■ “IIndexSearch2 :: IndexVolumeSets” on page 568

■ “IIndexSearch2 :: ListIndexVolumeSets” on page 590

■ “IIndexVolumeSet :: FirstItemIndexSequenceNumber” on page 620

■ “IIndexVolumeSet :: OldestArchivedDate” on page 621

■ “IIndexVolumeSet :: YoungestArchivedDate” on page 622

■ “IIndexVolumeSets :: Item” on page 613

■ “IIndexVolumeSets :: _NewEnum” on page 611

Page 607: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

607Search APIIIndexVolumeSets :: ArchiveEntryId

IIndexVolumeSets :: ArchiveEntryIdThis property returns the archive Id of the archive to which the index volume set belongs.

The property is read only.

SyntaxHRESULT ArchiveEntryId([out,retval] BSTR* value);

Parameters

RemarksGets the ArchiveEntryId associated with the current index volume sets.

SelectArchive must be called prior to using this property.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");IIndexVolumeSets volSets =

(IIndexVolumeSets)search.IndexVolumeSets;string aeid = volSets.ArchiveEntryId;

[out,retval] BSTR* value Pointer to a string that will hold the currently selected archive Id.

rvS_OK Success.

rvE_POINTER The pointer passed in to receive the current value is invalid.

Page 608: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

608 Search APIIIndexVolumeSets :: ArchiveName

IIndexVolumeSets :: ArchiveNameThis property returns the name of the archive to which the index volume set belongs.

The property is read only.

SyntaxHRESULT ArchiveName([out,retval] BSTR* value);

Parameters

RemarksSelectArchive must be called prior to using this property.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;string archName = volSets.ArchiveName;

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

rvS_OK Success.

rvE_POINTER The pointer to a string passed to the property is invalid.

Page 609: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

609Search APIIIndexVolumeSets :: HasFolders

IIndexVolumeSets :: HasFoldersThis property indicates whether the archive contains a folder structure.

The property is read only.

SyntaxHRESULT HasFolders([out,retval] VARIANT_BOOL* value);

Parameters

RemarksSelectArchive must be called prior to using this property.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;if (volSets.HasFolders == true){ //do something

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain a true value if the archive contains a folder structure.

rvS_OK Success.

rvE_POINTER The pointer to a string passed in to receive the current value is invalid.

Page 610: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

610 Search APIIIndexVolumeSets :: Count

IIndexVolumeSets :: CountThis property returns the number of index volume sets associated with the currently selected archive.

The property is read only.

SyntaxHRESULT Count([out,retval] long* value);

Parameters

RemarksSelectArchive must be called prior to using this property.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;for (int i = 1; i <= volSets.Count; i++){ IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i); //do something

[out,retval] long* value Long pointer to receive the current number of index volume sets for the current archive.

rvS_OK Success.

rvE_POINTER The long integer pointer passed to the parameter to receive the current value is not valid.

Page 611: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

611Search APIIIndexVolumeSets :: _NewEnum

IIndexVolumeSets :: _NewEnumThis property returns an IEnumVARIANT interface on an object that can be used to enumerate the collection. This property is hidden in VBScript.

SyntaxHRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters

RemarksThis property is a standard property used to support enumerating collections, it is automatically used internally when you use the For Each construct in C#, VBScript.

SelectArchive must be called prior to using this property.

Return value

ExamplesThe following examples show how to enumerate the Index Volume Sets in an Index Search object.

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");IIndexVolumeSets volSets = (IIndexVolumeSets)search.IndexVolumeSets;foreach (IIndexVolumeSet volSet in volSets){ //do something

[out,retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed to the property is invalid.

Page 612: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

612 Search APIIIndexVolumeSets :: _NewEnum

See also“IIndexVolumeSets :: Item” on page 613

Page 613: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

613Search APIIIndexVolumeSets :: Item

IIndexVolumeSets :: ItemThis property returns an index volume set instance from the collection, based on the index value passed to it.

The property is read only.

SyntaxHRESULT Item([in] long index,

[out,retval] IUnknown** indexVolumeSet);

Parameters

RemarksThis property provides an alternative method to _NewEnum for accessing the IIndexVolumeSet pointers contained in the collection.

IIndexSearch2::SelectArchive must be called prior to using this property.

Return value

Example

C#search.SelectArchive("183B7B0F0D085C5428A46D163C39922E61110000evsite1");

[in] long index The 1-based index of index volume sets in the collection.

[out,retval] IUnknown** indexVolumeSet Returns an IUnknown interface to the index volume set object.

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed to the property is invalid.

rvE_INVALIDARG

Page 614: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

614 Search APIIIndexVolumeSets :: Item

IIndexVolumeSets volSets =(IIndexVolumeSets)search.IndexVolumeSets;

for (int i = 1; i <= volSets.Count; i++){

IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(i);//do something

C++#import "IndexClient.dll"using namespace EVIndexClient;

long volSetCount = 0;IIndexVolumeSetsPtr volSets;IIndexVolumeSetPtr volumeSet;

indexSearch.SelectArchive(archiveId);

volSets = indexSearch.IndexVolumeSets();volSetCount = volSets.Count();

for(long i = 1; i <= volSetCount; ++i){

volumeSet = volSets.Item(i);

// Display the volume set details, ensure date time values are returned and displayed in local system time

volumeSet.PutDateTimesUTC(VARIANT_FALSE);DisplayVolumeSet(volumeSet);

}

See also■ “IndexVolumeSet object” on page 615

■ “IIndexVolumeSets :: _NewEnum” on page 611

Page 615: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

615Search APIIndexVolumeSet object

IndexVolumeSet objectThe IndexVolumeSet object implements the following interface:

■ IIndexVolumeSet

IIndexVolumeSet interface provides a set of properties that can be used to query a particular index volume set for the current archive.

IndexVolumeSet pointers can be obtained using the IIndexVolumeSets interface that enables users to iterate through the index volume sets for an archive.

Syntaxinterface IIndexVolumeSet : IDispatch

Member summary

Property Read/Write Description

Identity Read only The Id of the current index volume set.

ArchiveEntryID Read only The archive Id of the archive to which the index volume set collection belongs.

ArchiveName Read only The name of the archive to which the index volume set belongs.

FirstItemIndexSequenceNumber Read only Each indexed item in an archive has a unique Index Sequence Number (ISN). The order of index volumes is defined by the ISN of the first item in the index volume.

OldestArchivedDate Read only Archived date of oldest item referenced in this index volume set.

YoungestArchivedDate Read only Archived date of youngest item referenced in this index volume set.

OldestItemDate Read only The oldest date property of the items indexed in the index volume set.

YoungestItemDate Read only The youngest date property of the items indexed in the index volume set.

Page 616: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

616 Search APIIndexVolumeSet object

RemarksIIndexVolumeSet interface pointers can be obtained using the properties of the IIndexVolumeSets interface that allows you to iterate through the index volume sets for an archive.

See “Remarks” on page 605.

Example

C#The following examples show two ways of obtaining an object of type IIndexVolumeSet. Both ways assume that an object of type IIndexVolumeSets, 'volSets', has been obtained.IIndexVolumeSet volSet = (IIndexVolumeSet)volSets.Item(index);//index is a '1' based index into the collection of IIndexVolumeSets

or//Use the 'foreach' method with IIndexVolumeSets::_NewEnum: foreach (IIndexVolumeSet volSet in volSets){

//do something

See also■ “IndexVolumeSets object” on page 605

DateTimesUTC Read/Write Indicates whether property values of type VT_DATE are returned as UTC or local system time. By default, items are always archived using UTC time.

Property Read/Write Description

Page 617: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

617Search APIIIndexVolumeSet :: Identity

IIndexVolumeSet :: IdentityThis property returns the Id of the current index volume set.

The property is read only.

SyntaxHRESULT Identity([out,retval] LONG* value);

Parameters

Return value

Example

C#IIndexVolumeSets volSets = (IIndexVolumeSets) search.IndexVolumeSets;foreach (IIndexVolumeSet volSet in volSets){

search.SelectIndexVolumeSet(volSet.Identity);DoSearch(search, 500);

}

[out,retval] LONG* value Pointer to a long integer which will receive the current value.

rvS_OK Success.

rvE_POINTER The long integer pointer passed into the property is invalid.

Page 618: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

618 Search APIIIndexVolumeSet :: ArchiveEntryID

IIndexVolumeSet :: ArchiveEntryIDThis property returns the archive Id of the archive to which the index volume set collection belongs.

The property is read only.

SyntaxHRESULT ArchiveEntryId([out,retval] BSTR* value);

Parameters

Return value

Example

C#string archId = volSet.ArchiveEntryId;

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

rvS_OK Success.

rvE_POINTER The string pointer passed into the property is invalid.

Page 619: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

619Search APIIIndexVolumeSet :: ArchiveName

IIndexVolumeSet :: ArchiveNameThis property returns the name of the archive to which the index volume set collection belongs.

The property is read only.

SyntaxHRESULT ArchiveName([out,retval] BSTR* value);

Parameters

Return value

Example

C#string archId = volSet.ArchiveName;

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

rvS_OK Success.

rvE_POINTER Pointer to a string that will contain the current Id.

Page 620: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

620 Search APIIIndexVolumeSet :: FirstItemIndexSequenceNumber

IIndexVolumeSet :: FirstItemIndexSequenceNumberThis property returns the Index Sequence Number (ISN) of the first item in the index volume set.

The property is read only.

SyntaxHRESULT FirstItemIndexSequenceNumber([out,retval] VARIANT* value);

Parameters

RemarksThe value of this property determines the order of volume sets in the collection.

The number is returned as a VARIANT and could be either a variant type VT_I4 or VT_I8. In Windows 2000, VT_I8 is not supported, so variant type will be VT_DECIMAL.

Return value

Example

C#object obj = volSet.FirstIndexSequenceNumber;

[out,retval] VARIANT* value Pointer to a VARIANT that will receive the index number.

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed to the property is not valid.

Page 621: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

621Search APIIIndexVolumeSet :: OldestArchivedDate

IIndexVolumeSet :: OldestArchivedDateThis property returns the oldest archived date of the items indexed in the index volume set.

The property is read only.

SyntaxHRESULT OldestArchivedDate([out,retval] VARIANT* value);

Parameters

RemarksThis date value is returned as VARIANT. The variant type will be VT_DATE.

Return value

Example

C#object obj = volSet.OldestArchivedDate;DateTime dateTime = (DateTime)obj;

[out,retval] VARIANT* value Pointer to a VARIANT containing the oldest archived date in the index volume set.

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed to the property is invalid.

Page 622: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

622 Search APIIIndexVolumeSet :: YoungestArchivedDate

IIndexVolumeSet :: YoungestArchivedDateThis property returns the youngest archived date of the items indexed in the index volume set.

The property is read only.

SyntaxHRESULT YoungestArchivedDate([out,retval] VARIANT* value);

Parameters

RemarksThis date value is returned as VARIANT. The variant type will be VT_DATE.

Return value

Example

C#object obj = volSet.YoungestArchivedDate;DateTime dateTime = (DateTime)obj;

[out,retval] VARIANT* value Pointer to a VARIANT that will receive the youngest archived date in the index volume set.

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed in to the property is invalid.

Page 623: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

623Search APIIIndexVolumeSet :: OldestItemDate

IIndexVolumeSet :: OldestItemDateThis property returns the oldest item in the index.

The property is read only.

SyntaxHRESULT OldestItemDate([out,retval] VARIANT* value);

Parameters

RemarksThis date value is returned as VARIANT. The variant type will be VT_DATE.

Return value

Example

C#object obj = volSet.OldestItemDate;DateTime dateTime = (DateTime)obj;

[out,retval] VARIANT* value Pointer to a VARIANT that will receive the oldest date of items in the index volume set.

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed to the property is invalid.

Page 624: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

624 Search APIIIndexVolumeSet :: YoungestItemDate

IIndexVolumeSet :: YoungestItemDateThis property returns the youngest item in the index.

The property is read only.

SyntaxHRESULT YoungestItemDate([out,retval] VARIANT* value);

Parameters

RemarksThis date value is returned as VARIANT. The variant type will be VT_DATE.

Return value

Example

C#object obj = volSet.YoungestItemDate;DateTime dateTime = (DateTime)obj;

[out,retval] VARIANT* value Youngest date of items in the index volume set.

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed to the property is invalid.

Page 625: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

625Search APIIIndexVolumeSet :: DateTimesUTC

IIndexVolumeSet :: DateTimesUTCThis property indicates whether property values of type VT_DATE are returned as UTC or local system time.

The property is read/write.

SyntaxHRESULT DateTimesUTC([in] VARIANT_BOOL value);HRESULT DateTimesUTC([out,retval] VARIANT_BOOL* value);

Parameters

Return value

Example

C#[in]IIndexVolumeSets volSets = (IIndexVolumeSets) search.IndexVolumeSets;foreach (IIndexVolumeSet volSet in volSets){ //make sure we return the datetime in local system time volSet.DateTimeUTC = false; object obj = volSet.YoungestItemDate; DateTime dateTime = (DateTime)obj; DateTime dt = new DateTime(2006, 12, 31); if (dateTime > dt) { //do something

[in] VARIANT_BOOL value VARIANT_BOOL containing the new value to set.

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive the current value.

rvS_OK Success.

rvE_POINTER The VARIANT_BOOL pointer passed to the property is invalid.

Page 626: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

626 Search APIIIndexVolumeSet :: DateTimesUTC

} else //do something else}[out]IIndexVolumeSets volSets = (IIndexVolumeSets) search.IndexVolumeSets;foreach (IIndexVolumeSet volSet in volSets){ bool utc = volSet.DateTimeUTC;

Page 627: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

627Search APISearchResults object

SearchResults objectThe SearchResults object implements the following interfaces:

■ ISearchResults

■ ISearchResults2

These interfaces provide a set of methods and properties that can be used to query and manage results returned from a search operation. Each result is represented by an SearchResult object.

Syntaxinterface ISearchResults2 :ISearchResults : IDispatch

Member summary

Property Read/Write Description

ISearchResults::Results Read/Write Pointer to the SearchResults object, which contains the results (as XML) returned from a search.

ISearchResults::Count Read only The number of results in this SearchResults object.

ISearchResults::Total Read only Total number of results that matched the search query.

ISearchResults::Start Read only Position in the set of results of the first result in this SearchResults object.

ISearchResults::Options Read only Value of the Options property of the IndexSearch2 object used to generate this set of results. This defines the granularity of the search results.

ISearchResults::SortBy Read only Name of the properties used to order the search results.

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

Page 628: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

628 Search APISearchResults object

ExampleAn object of type ISearchResults2 is obtained from a call to IIndexSearch2::Search, or by creating it directly and initializing it with a set of pre-existing results.

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");

or ISearchResults2 results = (ISearchResults2) new SearchResults();//assume we have a set of results in xml, held in the string xmlResultsresults.Results = xmlResults;

Method Read/Write Description

ISearchResults::Item Read only Set of results object returned by enumeration.

ISearchResults2::InSync Read only Indicates whether or not the index is synchronized with the current contents of the archive.

ISearchResults2::TruncationReason Read only Reasons for truncated search results.

ISearchResults2::DateTimesUTC Read/Write Whether property values of type VT_DATE are returned as UTC or local system time.

ISearchResults2::LoadResults Write only Loads search results XML from IStream or SAFEARRAY of bytes or a string (BSTR).

Page 629: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

629Search APIISearchResults :: Results

ISearchResults :: ResultsThis property gets or sets an XML text string which represents the results string.

The property is read/write.

SyntaxHRESULT Results([out, retval] BSTR *pbsResults,

[in, string] BSTR bsResults);

Parameters

RemarksSearch results are stored in XML and can be retrieved or set using this property. If a new string is stored then any previous results will be lost.

Return value

Example

C#[out]ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");

[out, retval] BSTR *pbsResults Pointer to a string that will receive the XML results string.

[in, string] BSTR bsResults String that contains an XML results string to initialize the object.

rvS_OK Success.

rvE_POINTER The BSTR pointer passed in to the property is invalid.

rvS_FALSE

vE_INVALIDARG

rvE_NOINTERFACE

Page 630: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

630 Search APIISearchResults :: Results

//get the results in XMLstring xmlResults = results.Results;[in]//assume that a previous results set has been stored in the string ’xmlResults’ISearchResults2 src = (ISearchResults2) new SearchResults();//initialise the new object with some existing resultssrc.Results = xmlResults;

Page 631: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

631Search APIISearchResults :: Count

ISearchResults :: CountThis property returns the number of results found by the Search operation.

The property is read only.

SyntaxHRESULT Count([out, retval] long *plCount);

Parameters

RemarksThe number of results returned in this SearchResults object may differ from the number of results requested.

Return value

Example

C#The following example gives an alternative approach to using 'foreach' to enumerate the results returned.ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");int num = results.Count;for (int i = 1; i <= num; i++){ ISearchResult2 res = (ISearchResult2)results.Item(i);

[out, retval] long *plCount Long integer pointer that will receive the number found.

rvS_OK Success.

rvE_POINTER The long integer pointer passed into the property is invalid.

Page 632: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

632 Search APIISearchResults :: Total

ISearchResults :: TotalThis property returns the total number of results that matched the search query.

The property is read only.

SyntaxHRESULT Total([out, retval] long *plTotal);

Parameters

RemarksTotal refers to the total number of hits for the query. This number should be greater than, or equal to, the number of results (Count).

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");long num = results.Count;long total = results.Total;if (total < num){ //an error has ooccured as the total should be at least equal to

the number results returned

[out, retval] long *plTotal Pointer to a long integer that will receive the total.

rvS_OK Success.

rvE_POINTER The long integer pointer passed into the property is invalid.

Page 633: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

633Search APIISearchResults :: Start

ISearchResults :: StartThis property returns the start position in the entire set of results of the first result in this SearchResults object.

The property is read only.

SyntaxHRESULT Start([out, retval] long *plStart);

Parameters

RemarksThis value can be from 1 to Total.

A search application will not know what the value of Total is on the first call to Search.

Note that Total can also change between calls to consecutive searches, as result of newly archived, indexed and deleted items.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");long start = results.Start;

[out, retval] long *plStart Pointer to a long integer that will receive the start position of the first result in this SearchResults object. Value can be from 1 to Total.

rvS_OK Success.

rvE_POINTER The long integer pointer that was passed to the property is invalid.

Page 634: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

634 Search APIISearchResults :: Options

ISearchResults :: OptionsThis property returns the value of the Options property of the IndexSearch2 object used to generate this set of results. The property contains search option flags that define the granularity of search results.

The property is read only.

SyntaxHRESULT Options([out, retval] long *plOptions);

Parameters

RemarksThis property retrieves the value that indicates the granularity used to generate the set of results.

See “IIndexSearch2 :: Options” on page 570.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");EOptionsFlags eof = (EOptionsFlags )results.Options;if (eof == EOptionsFlags.roAttachmentGranularity){ //do something}else //do something else

[out, retval] long *plOptions Pointer to a long integer that will receive the value.

rvS_OK Success.

rvE_POINTER The long integer pointer passed into the property is invalid.

Page 635: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

635Search APIISearchResults :: SortBy

ISearchResults :: SortByThis property returns the value of the SortBy property of the IndexSearch2 object used to generate this set of results. The property is used to order the returned search results.

The property is read only.

SyntaxHRESULT SortBy([out, retval] BSTR *pbsSortBy);

Parameters

RemarksSee “IIndexSearch2 :: SortBy” on page 572.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");string sortBy = results.SortBy;

[out, retval] BSTR *pbsSortBy Pointer to a string that will receive the current value

rvS_OK Success.

rvE_POINTER The string pointer passed into the property is invalid.

Page 636: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

636 Search APIISearchResults :: _NewEnum

ISearchResults :: _NewEnumThis property returns an IEnumVARIANT interface on an object that can be used to enumerate the SearchResults collection. This property is hidden in VBScript.

The property is read only.

SyntaxHRESULT _NewEnum([out,retval] IUnknown** enumerator);

Parameters

RemarksThis property is a standard property used to support enumerating collections, it is automatically used internally when you use the foreach construct in C# or VBScript.

This property provides an alternative to Item for iterating through the collection.

Return value

ExampleThis property is not normally called explicitly; it allows the use of ’foreach', as shown in the following example.

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results){

[out,retval] IUnknown** enumerator Returned reference to the IUnknown interface of the object.

rvS_OK Success.

rvE_POINTER The pointer to the IUnknown pointer passed to the property is invalid.

Page 637: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

637Search APIISearchResults :: _NewEnum

//do something

Page 638: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

638 Search APIISearchResults :: Item

ISearchResults :: ItemThis method is used to return the specified item in the SearchResult collection object. The value returned is an ISearchResult interface pointer which provides properties and methods to allow the user to extract the results data.

SyntaxHRESULT Item([in] long lIndex,

[out, retval] LPVARIANT pvResult);

Parameters

RemarksThis property can be used in place of the _NewEnum property to iterate through the collection.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");int num = results.Count;for (int i = 1; i <= num; i++){ ISearchResult2 res = (ISearchResult2)results.Item(i);

[in] long lIndex The index number of the result required in the SearchResult collection.

[out, retval] LPVARIANT pvResult Pointer to a VARIANT that will receive the ISearchResult pointer.

rvS_OK Success.

rvE_POINTER The LPVARIANT passed into the method is invalid.

rvE_INVALIDARG The value of the first parameter, lIndex, is either less than 1 or greater than the number of results returned.

Page 639: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

639Search APIISearchResults :: Item

See also■ “SearchResult object” on page 646

Page 640: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

640 Search APIISearchResults2 :: InSync

ISearchResults2 :: InSyncThis property indicates whether or not the index is synchronized with the current contents of the archive.

The property is read only.

SyntaxHRESULT InSync([out,retval] VARIANT_BOOL* value);

Parameters

RemarksTypically a false value indicates that the index is currently being updated.

Return value

Example

C#ISearchResults2 results = (ISearchResults2)search.Search(query.Query, 1, 100, "");bool inSync = results.InSync;if (inSync == false){ MessageBox.Show("It is possible that the index was being updated

as the search was being carried out", "Index not synchronised",MessageBoxButtons.OK, MessageBoxIcon.Warning);

}else //carry on as normal

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will contain the current value.

rvS_OK Success.

rvE_POINTER The VARIANT_BOOL pointer passed in to receive the current value is invalid.

Page 641: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

641Search APIISearchResults2 :: TruncationReason

ISearchResults2 :: TruncationReasonThis property indicates the reason, if any, for incomplete search results.

The property is read only.

SyntaxHRESULT TruncationReason([out,retval] ETruncationReason* value);

Parameters

RemarksFor the values that ETruncationReason can have, see “ETruncationReason enumeration” on page 536.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");ETruncationReason tr = (ETruncationReason)results.TruncationReason;if (tr == ETruncationReason.trNone){ //carry on processing}else{ switch (tr) { case ETruncationReason.trAdminResultLimitExceeded:

[out,retval] ETruncationReason* value Pointer to an ETruncationReason value which contains the reason for truncation.

rvS_OK Success.

rvE_POINTER The ETruncationReason pointer passed into the property is invalid

Page 642: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

642 Search APIISearchResults2 :: TruncationReason

//handle the problem break; case ETruncationReason.trAdminTimeoutExpired: //handle the problem break; //and so on for the other reasons

Page 643: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

643Search APIISearchResults2 :: DateTimesUTC

ISearchResults2 :: DateTimesUTCThis property indicates whether date/time property values are returned as UTC or local system time.

The property is read/write.

SyntaxHRESULT DateTimesUTC([in] VARIANT_BOOL value);HRESULT DateTimesUTC([out,retval] VARIANT_BOOL* value);

Parameters

RemarksBy default, items are returned as UTC time.

Return value

Example

C#[in]ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");//make sure date/time values are returned in local system timeresults.DateTimesUTC = false;[out]ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");if (results.DateTimesUTC == true){

[in] VARIANT_BOOL value VARIANT_BOOL that will set a new value.

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL that will receive the current value.

rvS_OK Success.

rvE_POINTER The VARIANT_BOOL pointer passed in to receive the current value is invalid.

Page 644: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

644 Search APIISearchResults2 :: DateTimesUTC

//do something

Page 645: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

645Search APIISearchResults2 :: LoadResults

ISearchResults2 :: LoadResultsThis method can be used to load an instance of ISearchResults2 with the XML results returned by the IIndexSearch2.SearchToXML method.

SyntaxHRESULT LoadResults([in] VARIANT rResultsXML);

Parameters

RemarksFor information on the XML schema used to return the search results, consult Symantec support.

If possible, use the SearchResults object rather than processing the XML directly.

The VARIANT may contain an IStream, byte array (SAFEARRAY) or a string (BSTR) containing the XML.

Return value

Example

C#In this example, it is assumed that there is a string holding a set of XML results from a previous search, called xmlResults.ISearchResults2 results = (ISearchResults2) new SearchResults();results.LoadResults(xmlResults);

[in] VARIANT rResultsXML VARIANT containing the XML to load.

rvS_OK Success.

rvE_INVALIDARG The VT TYPE of the VARIANT is incorrect.

rvS_FALSE The XML is empty or the VT TYPE is VT_EMPTY.

Page 646: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

646 Search APISearchResult object

SearchResult objectThe SearchResult object implements the following interfaces:

■ ISearchResult

■ ISearchResult2

These interfaces provide methods and properties that allow the user to examine the individual results returned after a call to Search.

Syntaxinterface ISearchResult2 : ISearchResult : IDispatch

Member summary

RemarksISearchResult interface pointers are obtained by using either ISearchResults::_NewEnum and iterating through the collection, or by using ISearchResults::Item to obtain a specific pointer from the collection.

Property Read/Write Description

ISearchResult::Result Read/Write Gets or sets an XML string containing the search result.

ISearchResult::Number Read only Returns a unique Id for this result.

ISearchResult2::Count Read Returns the number of properties in this search result.

ISearchResult2::DateTimesUTC Read/Write Gets or sets the value of the DateTimesUTC setting.

Method Description

ISearchResult::Prop Obtains the value of a specific property from the result.

ISearchResult::Prop2 Obtains the value of a specific custom property from the result.

ISearchResult2::Item Gets the property at the 1-based position in the collection.

Page 647: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

647Search APISearchResult object

Example

C#The following examples show two different ways of iterating through results in a SearchResults collection object. It is assumed there is an ISearchResults2 object, 'results', obtained from a search.ISearchResult2 res = (ISearchResult2)results.Item(index);//index is a '1' based index into the collection of ISearchResult's.

orforeach (ISearchResult2 res in results) {

Page 648: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

648 Search APIISearchResult :: Result

ISearchResult :: ResultThis property is used to get an XML string for this result or to set a new XML string.

SyntaxHRESULT Result([out, retval] BSTR *pbsResult,

[in, string] BSTR bsResult);

Parameters

RemarksThis property is simply the XML string for the search result stored in this result object, or an empty string if the object is not initialized. It can also be used to store an XML result. Any previous result will be overwritten.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results){ string xmlResult = res.Result; //do something

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

[in, string] BSTR bsResult String that contains a new XML string to set.

rvS_OK Success.

rvE_POINTER The string pointer passed in to receive the current value is invalid.

rvS_FALSE The XML string passed in is zero length.

Page 649: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

649Search APIISearchResult :: Number

ISearchResult :: NumberThis property returns the unique identifier for this result.

SyntaxHRESULT Number([out, retval] long *plNumber);

Parameters

RemarksReturns the unique identifier for this result within the collection. The Id is stored in the NUMBER attribute of each XML result tag.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results){ long number = res.Number;

[out, retval] long *plNumber Pointer to a long integer that will contain the number.

rvS_OK Success.

rvE_POINTER The long integer pointer passed in to retrieve the value is invalid.

Page 650: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

650 Search APIISearchResult :: Prop

ISearchResult :: PropThis method returns the specified property for the current result.

SyntaxHRESULT Prop([in, string] BSTR bsName,

[out, retval] LPVARIANT pvVal);

Parameters

RemarksThe value returned can be either a date, string or integer. If the value is multi-valued, the returned VARIANT is an array of VARIANTS, each of which contains a date, string or integer value.

The following VARIANT types may be returned: VT_I4, VT_UI4, VT_I8, VT_DECIMAL, VT_DATE, VT_BSTR or VT_EMPTY.

The name can be that of a custom property, in the propertySet.propertyName format.

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results)

[in, string] BSTR bsName String containing the name of the property.

[out, retval] LPVARIANT pvVal Pointer to a VARIANT that will contain the property value.

rvS_OK Success.

rvE_POINTER The VARIANT point passed in to receive the property value is invalid.

rvS_FALSE Property not found.

Page 651: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

651Search APIISearchResult :: Prop

{object obj = res.Prop("ssid");

string ssid = (string)obj;RetrieveItem(ssid);

Page 652: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

652 Search APIISearchResult :: Prop2

ISearchResult :: Prop2This method is used to get the value of a specific custom property.

SyntaxHRESULT Prop2([in] BSTR bsName,

[in] BSTR bsPropertySet, [in] BSTR bsPropertyName, [out, retval] LPVARIANT pvVal);

Parameters

RemarksThis method returns the value of a custom property. If the requested property does not exist, an initialized but empty VARIANT will be returned.

The value returned can be either a date, string or integer. If the value is multi-valued, the returned VARIANT is an array of VARIANTS, each of which contains a date, string or integer value.

The following VARIANT types may be returned: VT_I4, VT_UI4, VT_I8, VT_DECIMAL, VT_DATE, VT_BSTR or VT_EMPTY.

Return value

[in] BSTR bsName This parameter is not currently used.

[in] BSTR bsPropertySet String containing the name of the property set to which the property belongs.

[in] BSTR bsPropertyName String containing the name of the property.

[out, retval] LPVARIANT pvVal Pointer to a VARIANT that will receive the value of the property.

rvS_OK Success.

rvE_POINTER The VARIANT pointer passed in to receive the value is invalid.

rvS_FALSE The custom property could not be found.

Page 653: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

653Search APIISearchResult :: Prop2

Example

C#This example assumes there is a custom property set, "CustomTags", which has an integer property, "Importance".ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results){ int tag = 0; //the prop we want should be an int but make sure object obj = res.Prop2("CustomTags", "Importance"); Type type = obj.GetType(); if (type.Name == "Int32") { tag = (int)obj;

Page 654: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

654 Search APIISearchResult2 :: Count

ISearchResult2 :: CountThis property returns the number of properties in the current search result.

The property is read only.

SyntaxHRESULT Count([out, retval] long* count);

Parameters

Return value

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results){

int count = res.Count;for (int i = 1; i < = count; i++){

object objProp = null;object objVal = null;res.Item(i, out objProp, out objVal);if ((string)objProp == "ssid")

{string ssid = (string)objVal;//do something

[out, retval] long* count Long pointer that will receive the number of properties in search result.

rvS_OK Success.

rvE_POINTER The long integer pointer passed into receive the count number is invalid.

Page 655: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

655Search APIISearchResult2 :: Item

ISearchResult2 :: ItemThis method returns the property name and value of the property at the position in the index specified by the first parameter.

SyntaxHRESULT Item([in] long index,

[out] LPVARIANT propertyName, [out] LPVARIANT propertyValue);

Parameters

RemarksUse this method to obtain the name and value of a property at a specific position in the collection. Note that the collection is 1-based not 0-based.

The value returned can be either a date, string or integer. If the value is multi-valued, the returned VARIANT is an array of VARIANTS, each of which contains a date, string or integer value.

The following VARIANT types may be returned: VT_I4, VT_UI4, VT_I8, VT_DECIMAL, VT_DATE, VT_BSTR or VT_EMPTY.

The name can be that of a custom property, in the propertySet.propertyName format.

Return value

[in] long index The index position of the required property.

[out] LPVARIANT propertyName Pointer to a VARIANT that contains the name of the property.

[out] LPVARIANT propertyValue Pointer to a VARIANT that will contain the value assigned to the property.

rvS_OK Success.

rvE_POINTER One of the VARIANT pointers passed to the method is invalid.

rvE_INVALIDARG The index was outside the range 1 to the number of properties.

Page 656: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

656 Search APIISearchResult2 :: Item

Example

C#ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results){ int count = res.Count; for (int i = 1; i < = count; i++) { object objProp = null; object objVal = null; res.Item(i, out objProp, out objVal); if ((string)objProp == "ssid") { string ssid = (string)objVal; //do something

Page 657: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

657Search APIISearchResult2 :: DateTimesUTC

ISearchResult2 :: DateTimesUTCThis property indicates whether property values of type VT_DATE are returned as UTC or local system time.

The property is read/write.

SyntaxHRESULT DateTimesUTC([in] VARIANT_BOOL value,

[out,retval] VARIANT_BOOL* value);

Parameters

RemarksBy default, items are always archived using UTC time.

Return value

Example

C#[in]ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");foreach (ISearchResult2 res in results){ //make sure date/times are returned in local system time res.DateTimesUTC = false; //do something[out]ISearchResults2 results =

(ISearchResults2)search.Search(query.Query, 1, 100, "");

[in] VARIANT_BOOL value VARIANT_BOOL containing the new value to set.

[out,retval] VARIANT_BOOL* value Pointer to a VARIANT_BOOL which will receive the current value.

rvS_OK Success.

rvE_POINTER Value is an invalid pointer.

Page 658: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

658 Search APIISearchResult2 :: DateTimesUTC

foreach (ISearchResult2 res in results){ bool isUTC = res.DateTimesUTC; //do something

Page 659: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Appendix

A

About Enterprise Vault indexes

This section provides more detailed information about Enterprise Vault indexes.

About index volume sets and volumesEach archive index comprises one or more sequential index volume sets. An index volume set contains an index volume. (Currently, an index volume set can contain only one index volume). Each index volume contains index entries for the items stored in the archive.

See Figure 8-1 on page 519.

An index volume can contain approximately three to five million index documents. The maximum number of index entries for a volume will depend on the level of indexing set and the number of properties indexed for each item. When an index volume is full, the Enterprise Vault Indexing service automatically creates a new index volume set (containing a new index volume).

The Enterprise Vault administrator uses the Enterprise Vault Administration Console to configure the physical locations to be used by the Indexing service when creating new indexes for archives.

Typically, user mailbox indexes will require only a single volume. Indexes for larger archives, such as file system archives and journal archives, are quite likely to have multiple volumes.

About index propertiesEnterprise 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.

Page 660: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

660 About Enterprise Vault indexesAbout index schemas

In addition to the system index properties, you can add custom index metadata properties to the index document for an item. These properties may be required to enable users or third-party applications to search for particular items. Custom index metadata can be added in the following ways:

■ Using the SimpleIndexMetadata interface of the Content Management API. An application that submits items to Enterprise Vault for archiving using the Content Management API can call the SimpleIndexMetadata methods and properties to add custom index metadata to the item before it is archived.

See “SimpleIndexMetadata object” on page 277.

■ Using the External Filtering API.

The IArchivingControl interface can be used to add custom index metadata properties as required by the external filter as an item is archived.

Note that custom index metadata properties cannot be added for attachments.

About index schemasThe contents of index entries differs depending on the index schema in use. This affects the way indexes are searched and the results returned.

There are two index schemas available with Enterprise Vault:

■ Default schema

■ Item Granularity Only schema

If you are using the Item Granularity Only schema, then the registry setting, SchemaType, will have a value of "1". This setting, if configured, is in the following location:HKEY_LOCAL_MACHINE \SOFTWARE \KVS \Enterprise Vault \Indexing

Which schema an installation uses will depend on the type of applications that will search the indexes. In general, any application that performs complex searches, such as those performed by Enterprise Vault Compliance and Discovery Accelerator products, should use the Item Granularity Only schema. The Item Granularity Only schema enables such searches to be performed considerably faster than the default schema.

If you have an existing Enterprise Vault environment, you need to consider the following if you decide to enable the Item Granularity Only schema:

■ After you enable the schema (using the SchemaType registry setting), only new indexes will be affected. Existing indexes need to be rebuilt in order to

Page 661: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

661About Enterprise Vault indexesAbout index schemas

use the new schema. If you have a very large number of archives, this could take a considerable time.

■ Users will see a difference in the number of results returned when searching with Enterprise Vault browser search or the Enterprise Vault search integrated with Outlook. By default, these search applications return both top-level items and individual attachments, and with the Item Granularity Only schema, they will not see individual attachments.

Default index schemaWith the default index schema, an index document is created for the top-level item (such as a message), and separate index documents are created for each attachment; each nested message and attachment is stored in a separate index document.

When a search is performed, each index document is searched, and all items that contain a match are returned as individual results; so results may contain both top-level items and attachments.

For example, a search for “John Doe” AND “Widgets Corp” will return any items or attachments that contain both “John Doe” and “Widgets Corp” in the same index document.

With this schema, performing a very complex search could result in a very large number of active queries in memory, potentially resulting in “out of memory” errors. For this reason, search query “chunking” settings may be required to limit the number of active queries in memory.

Item Granularity Only schemaWith the Item Granularity Only schema, there is a single index document for the top-level message and any attachments; this means that the top-level item and attachments are searched as a single item.

When a search is performed, the single index entity (containing both top-level items and attachments) is searched, and only top-level items are returned in the results. Even if the search criteria is only matched in one or more attachments, only the associated top-level item is returned in the results. Attachments can be accessed from the top-level items.

As index data for an item and any attachments are stored in the same index document, searches for terms that are combined using AND may return more results than are returned with the default schema. For example, a search for “John Doe” AND “Widgets Corp” may return an item which has “John Doe” in attachment 1 and “Widgets Corp” in attachment 3.

By combining the information from attachments into the top-level item in the index, the need to configure query “chunking” for very complex searching is

Page 662: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

662 About Enterprise Vault indexesAbout index schemas

removed. Complex searches, such as those performed by Enterprise Vault Compliance and Discovery Accelerator products, are considerably faster if this index schema is used.

Page 663: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Appendix

B

Enterprise Vault Properties

This section lists the properties that are defined by Enterprise Vault:

■ System properties

■ Defined custom properties

■ Defined custom FSA properties

■ Defined custom SharePoint properties

■ Defined custom properties for Compliance Accelerator.

When processing an item, Enterprise Vault populates properties with information in the item. This data is then stored with the archived item. Indexed properties are added to the archive index and can be used in archive searches.

Not all properties are present on every item, and the type library defines many more properties than are currently used. The data available in search results for each item is a subset of these properties; any properties that are to be returned in search results must be defined as retrievable.

Note: If you are using the Search API from a language that cannot access the string constants that are defined in the type library, any string literals used instead must match exactly the values from the type library. For example, for IndexPropSSID use "ssid".

In the following tables:

■ Searchable properties are those that can be used in search queries.

■ Retrievable properties are those that can be returned in search results.

■ Multi-valued properties can have multiple values for a single index entry.

Page 664: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

664 Enterprise Vault PropertiesSystem properties

■ Sortable properties are those that can be used to order search results. Properties marked with are optimized in the index for sorting and provide the quickest results.

System propertiesThis section lists the system properties defined in Enterprise Vault.

All properties in this table have defined constants, IndexPropXXXX, where XXXX is the uppercase form of the property name. For example, IndexPropSUBJ is the constant for the defined property, “subj”, and IndexPropRCAT is the constant for the system property, “rcat”.

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Subject/Title subj String

Message Priority prio String Although indexed as a string, usually a numeric value.

Technically no limit, practically limited to 32-bit integer maximum.

Message Importance impo String Although indexed as a string, usually a numeric value.

Technically no limit, practically limited to 32-bit integer maximum.

Message Sensitivity sens String Although indexed as a string, usually a numeric value.

Technically no limit, practically limited to 32-bit integer maximum.

Message Security secu String Currently not populated with any value.

Message Originator orgn String

Original identifier for the item. (e.g. SubmissionId for a sent message)

iden String

Last Modified date of the item

mdat Date Range 1 Jan 1970 to 31 Dec 2148

Page 665: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

665Enterprise Vault PropertiesSystem properties

Original identifier for this component of the item

coid String

Data type of the item dtyp String E.g. DOC, XLS, MSG

De-duplication fingerprint of item

fpdd String Can be used to find an exact match of a message or a document.

Content fingerprint of item

fpcn String Can be used to find a match on an attachment or document content.

Archived Date adat Date Range 1 Jan 1970 to 31 Dec 2148

Original location of the item

locn String A sequence of folders.

Current location of the item

clcn String A sequence of folders.

The last or leaf folder of original location

lolf String

The last or leaf folder of current location

cllf String

Original location folder names (ordered)

lofn String

Current location folder names (ordered)

clfn String

The item's Saveset identifier

ssid String See “Note 1” on page 676.

Max 72 chars. However, if you include any attachment num, as per Note 1, then the max number of chars is 76 + 1 + 10 => 87 chars.

Shortcut location shct String Not supported from Enterprise Vault 10.

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 666: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

666 Enterprise Vault PropertiesSystem properties

User who archived the item.

user String Currently not populated.

Original retention category Id

rcat String Max 112 chars.

Current retention category Id

crct String Max 112 chars.

Original retention category name

rcnm String Max 32 chars

Current retention category name

crcn String Max 32 chars

Index Sequence Number

snum Integer 64-bit integer

VaultEntryId of index containing the item

vlid String Max 112 chars.

Created, sent/received or archivedDate

date Date Range 1 Jan 1970 to 31 Dec 2148

See “Note 2” on page 676

Content cont String Search API: Only the first 120 significant characters can be retrieved.

Content Management API: HTML representation to a max of 5 MB.

See “Note 3” on page 676

Languages lang String Currently not populated.

Categories/Keywords keys String

The size of the item in KB

size Integer 32-bit integer

The number of attachments

natc Integer 32-bit integer

Permission VaultIds for the item. (Known as Archive Folder VaultIds)

pvid String Max 112 chars.

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 667: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

667Enterprise Vault PropertiesSystem properties

Attachment Number anum Integer 32-bit integer

Zero for top-level item.

In ItemGranularity schema, this property cannot be used in a query to limit hits on attachments or top level documents. This is because each index document contains the parent item and all the attachments.

Expiry date for the item (based on crct)

edat Date Range 1 Jan 1970 to 31 Dec 2148

Number of days to expiry for the item (based on crct)

ndte Integer 32-bit integer

Rank value of the item when sorted by relevance (0 to 10,000)

rank Integer 32-bit integer

The item's original MAPI Message Class (e.g. IPM.Note)

msgc String

Message Flag Status flag Integer 32-bit integer

Reason for missing content

comr String See “Note 4” on page 677

Technically no limit, practically limited to 32-bit integer max.

Attachments only. The author of the top-level item

taut String Not applicable to items indexed using ItemGranularity schema.

Attachments only. The subject/title of the top-level item

tsub String Not applicable to items indexed using ItemGranularity schema.

Attachments only. The size of the top-level item in KB

tsiz Integer 32-bit integer

Not applicable to items indexed using ItemGranularity schema.

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 668: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

668 Enterprise Vault PropertiesSystem properties

Conversation tracking ID

cnid String For MAPI items, a 32 hexadecimal character representing a 128-bit GUID. Currently not populated for other items.

Conversation tracking index

cnhv String For MAPI items, 12 hexadecimal characters representing a datetime, followed by 32 hexadecimal characters representing a 128-bit GUID, followed by 10 hexadecimal characters for each reply/forward.

Currently not populated for other items.

Conversation tracking topic

cntp String Currently only populated for MAPI items.

Index Volume. Identity of the volume containing the item

ivid Integer 32-bit integer

Index Volume Set. Identity of the volume set containing the item

vsid Integer 32-bit integer

Message Envelope recipient and sender information

menv String Only present for Exchange journal messages.

See “Note 5” on page 677

Retrievable using the Content Management API (see “IArchiveMetaData :: IndexData” on page 253)

Message Envelope Recipient. Union of jrto, jrcc, jrbc & jren

jrcp String Only present for Exchange journal messages. The property values include both email addresses and display names (where present).

Message Envelope TO: Recipient

jrto String Only present for Exchange journal messages.

See Notes for jrcp.

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 669: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

669Enterprise Vault PropertiesSystem properties

Message Envelope CC: Recipient

jrcc String Only present for Exchange journal messages.

See Notes for jrcp.

Message Envelope BCC: Recipient

jrbc String Only present for Exchange journal messages.

See Notes for jrcp.

Message Envelope Other Recipient

jren String Only present for Exchange journal messages.

See Notes for jrcp.

Used when the recipient details are not explicitly identified as a TO, CC, or BCC recipient.

Message Envelope Author Union of jrfm, jrpp & jaen

jrau String Only present for Exchange journal messages.

See Notes for jrcp.

Message Envelope FROM: Recipient

jrfm String Only present for Exchange journal messages.

See Notes for jrcp.

Message Envelope PP: RecipientPer Procurationem (by delegation to): person on whose behalf document has been written or message has been sent

jrpp String Only present for Exchange journal messages.

See Notes for jrcp.

Message Envelope Other Author

jaen String Only present for Exchange journal messages.

See Notes for jrcp.

Used when the author details are not explicitly identified as FROM or PP.

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 670: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

670 Enterprise Vault PropertiesSystem properties

Message Sender and Recipient

sere String See “Note 6” on page 678

Retrievable using the Content Management API (see “IArchiveMetaData :: IndexData” on page 253)

Message Recipient. Union of redn, reea, resm, reot & jrcp

recp String

Message Recipient. Display/friendly name. Union of rtdn, rcdn, rbdn & rndn

redn String

Message Recipient. Email address. Union of rtea, rcea, rbea & rnea

reea String

Message Recipient. SMTP email address. Union of rtsm, rcsm, rbsm & rnsm

resm String

Message Recipient. Other email address. Union of rtot, rcot, rbot & rnot

reot String

TO: Recipient reto String Max 256 chars.

The retrievable value is the first few RTDN (or RTSM) values, up to a maximum of 256 characters.

TO: Recipient. Display/friendly name

rtdn String

TO: Recipient.Email address. Union of RTSM & RTOT

rtea String

TO: Recipient.SMTP email address

rtsm String

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 671: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

671Enterprise Vault PropertiesSystem properties

TO: Recipient. Other email address

rtot String

CC: Recipient recc String Max 256 chars.

The retrievable value is the first few RTDN (or RTSM) values, up to a maximum of 256 characters.

CC: Recipient. Display/friendly name

rcdn String

CC: Recipient.Email address. Union of rcsm & rcot

rcea String

CC: Recipient.SMTP email address

rcsm String

CC: Recipient.Other email address

rcot String

BCC: Recipient rbcc String Max 256 chars.

The retrievable value is the first few RTDN (or RTSM) values, up to a maximum of 256 characters.

BCC: Recipient. Display/friendly name

rbdn String

BCC: Recipient.Email address. Union of rbsm & rbot

rbea String

BCC: Recipient.SMTP email address

rbsm String

BCC: Recipient.Other email address

rbot String

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 672: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

672 Enterprise Vault PropertiesSystem properties

Other Envelope Recipient

renv String Max 256 chars.

The retrievable value is the first few RTDN (or RTSM) values, up to a maximum of 256 characters.

Other Envelope Recipient. Display/friendly name

rndn String

Other Envelope Recipient. Email address. Union of rnsm & rnot

rnea String

Other Envelope Recipient.SMTP email address

rnsm String

Other Envelope Recipient.Other email address

rnot String

Number of Recipients nrcp Integer 32-bit integer

Number of TO: Recipients

nrto Integer 32-bit integer

Number of CC: Recipients

nrcc Integer 32-bit integer

Number of BCC: Recipients

nrbc Integer 32-bit integer

Number of Other Envelope Recipients

nren Integer 32-bit integer

Author. Union of audn, auea, ausm, auot, writ, from, ppgn & jrau

auth String

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 673: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

673Enterprise Vault PropertiesSystem properties

Author. Display/friendly name. Union of wrdn, frdn, ppdn

audn String

Author.Email address. Union of ausm, auot and wrea

auea String

Author. SMTP email address. Union of wrsm, frsm ppsm

ausm String

Author. Other email address. Union of wrot, frot, ppot

auot String

Writer.Union of wrdn, wrea, wrsm, wrot

writ String

Writer. Display/friendly name

wrdn String

Writer.Email address. Union of wrsm & wrot

wrea String

Writer.SMTP email address

wrsm String

Writer.Other email address

wrot String

FROM: Union of frdn, frea, frsm, frot

from String

FROM: Display/friendly name

frdn String

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 674: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

674 Enterprise Vault PropertiesSystem properties

FROM: Email address. Union of frsm & frot

frea String

FROM: SMTP e-mail address

frsm String

FROM: Other email address

frot String

PP Union of ppdn, ppea, ppsm & ppot. Per Procurationem (by delegation to) person on whose behalf document has been written or message has been sent

ppgn String

PP Display/friendly name

ppdn String

PP Exchange email address. Union of ppsm, ppot

ppea String

PP SMTP email address

ppsm String

PP Other email address

ppot String

Name Union of recp, auth

name String

Name Display/friendly name. Union of redn & audn

nadn String

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 675: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

675Enterprise Vault PropertiesSystem properties

Name Exchange email address. Union of reea & auea

naea String

Name SMTP email address. Union of resm & ausm

nasm String

Name Other email address. Union of reot & auot

naot String

Text Union of cont & subj

text String

Event start dateE.g. Calendar meeting start date

csrt Date Range 1 Jan 1970 to 31 Dec 2148

Event end dateE.g. Calendar meeting end date

cend Date Range 1 Jan 1970 to 31 Dec 2148

Event locationE.g. Calendar meeting location

clon String

Task due date tddt Date Range 1 Jan 1970 to 31 Dec 2148

Task completed date tcdt Date Range 1 Jan 1970 to 31 Dec 2148

Task status tsts Integer Property value can be one of the following:

0 = Not started1 = In progress2 = Completed3 = Paused4 = Deferred

Table B-1 System properties

Description Name Type Search-able

Retriev-able

Multi-Valued

FastSort-able

Notes

Page 676: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

676 Enterprise Vault PropertiesSystem properties

Note 1The ssid value returned for attachments is a concatenation of the SavesetId and the attachment number (see anum), separated by a full stop.

For example, for the first attachment:849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B0.1

To use the Content Management API to retrieve the item, the SavesetId must be extracted by removing the trailing full stop and attachment number:849000000000000~200002041641270000~0~2F0993C0D5BD4D0087E592D043C22B0

Note 2For a message, this is selected from the first of the following properties that is present on the message:Message Delivery Time (PR_MESSAGE_DELIVERY_TIME)Original Message Delivery Time (PR_ORIGINAL_DELIVERY_TIME)Submission Time (PR_CLIENT_SUBMIT_TIME)Original Message Submission Time (PR_ORIGINAL_SUBMIT_TIME)Message Transport Provider Submission Time (PR_PROVIDER_SUBMIT_TIME)Last Modification Time (PR_LAST_MODIFICATION_TIME)Creation Time (PR_CREATION_TIME)Deferred Delivery Time (PR_DEFERRED_DELIVERY_TIME)

For an attachment to a message or a document, this is the created date of the object (PR_CREATION_TIME).

In the extreme case that none of the above properties are available, then the current time (archival time) is used.

Note 3In the Search API, the value is the first 120 characters of the textual representation of the content.

In the Content Management API, the value is the HTML representation of the content to a maximum of 5 MB.

If the size is larger than 5 MB, no value is returned, but a content missing reason property (comr) with value vmrVALUENOTOBTAINED is returned instead.

The 5 MB limit can be changed using the registry value, HKEY_LOCAL_MACHINE\Software\KVS\Enterprise Vault\MaxIndexDataHTMLContentKB

Page 677: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

677Enterprise Vault PropertiesSystem properties

Note 4Predefined values for comr property:enum EValueMissingReason{vmrNOREASON =0 No reason availablevmrVALUENOTFOUND =1 Content does not existvmrVALUENOTOBTAINED =2 Content could not be obtainedvmrVALUECORRUPT =3 Content is (or appears to be) corruptvmrNOCONVERTER =4 Not possible to convert content to suitable format (i.e. no converter for this specific conversion)vmrCONVERSIONFAILED =5 Conversion of content failed (i.e. converter error)vmrCONVERSIONTIMEDOUT =6 Conversion of content timed outvmrFORMATEXCLUDED =7 Content requires conversion but its data format is excluded from conversionvmrCONVERSIONBYPASS =8 Content requires conversion but conversion bypass has been setvmrVALUEENCRYPTED =9 Content is encryptedvmrCONVERTERUNINIT =10 Content requires conversion but converters are not available, or have not been initializedvmrADDITEMTOINDEX =11 Unable to add content to indexvmrFORMATNOTRECOGNISED =12 Converters did not recognize the file typevmrLARGEFILE =13 Conversion excluded for large filesvmrUNKNOWNCODEPAGE =14 Conversion excluded for codepages we cannot detect (e.g. GB18030)

Note 5The menv property contains the Message Envelope recipient and sender information for journal messages, in XML format. The following is an example of what it can contain:

<?xml version="1.0" encoding="utf-16?"><MSGENV>

<RECP P1="true"><TO>

<RC><DN>Joe User</DN><EA>[email protected]</EA>

</RC><DL>

<DN>Internal Users</DN><EA>[email protected]</EA><RC>

<DN>Administrator</DN><EA>[email protected]</EA>

</RC><RC>

<DN>CEO</DN>

Page 678: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

678 Enterprise Vault PropertiesSystem properties

<EA>[email protected]</EA></RC>

</DL></TO><CC /><BCC>

<RC><DN>Jill User</DN><EA>[email protected]</EA>

</RC></BCC><ENV>

<RC><DN>John User</DN><EA>[email protected]</EA>

</RC></ENV>

</RECP><AUTH>

<FROM><DN>Chris Davies</DN> <EA>[email protected]</EA> </FROM><PP><DN>Bill Stephens</DN><EA>[email protected]</EA></PP>

</AUTH></MSGENV>

This example is not exhaustive. The full XSD also specifies DLs and their nesting.

The values returned for recipient properties (e.g. reto, renv) for envelope-journal items are returned from the envelope (P1) unless the message (P2) contains at least the same number of (or more) recipients for each index property.

The AUTH element contains the message sender/author details (FROM). Where a message has been sent on behalf of another user, the AUTH information will include both the sender (FROM) and delegate (PP) details.

Note 6The sere property contains the sender and recipient information in XML format.The following is an example of what it can contain:<?xml version="1.0" encoding="utf-16?"><MSG>

<RECP><TO>

<RC><DN>Joe User</DN><EA>[email protected]</EA>

</RC>

Page 679: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

679Enterprise Vault PropertiesSystem properties

<DL><DN>Internal Users</DN><EA>[email protected]</EA>

<RC><DN>Administrator</DN><EA>[email protected]</EA>

</RC><RC>

<DN>CEO</DN><EA>[email protected]</EA>

</RC></DL>

</TO><CC /><BCC />

</RECP><AUTH>

<FROM><DN>Chris Davies</DN> <EA>[email protected]</EA></FROM><PP><DN>Bill Stephens</DN>

<EA>[email protected]</EA></PP>

</AUTH></MSG>

This example is not exhaustive. The sere property follows the same schema as the menv property, except that the root node is <MSG> rather than <MSGENV>.

Version information■ The sere property is available in Enterprise Vault 6.0 SP5, Enterprise Vault

7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 31.

■ <AUTH> element of the menv property is available in Enterprise Vault 6.0 SP5, Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 31.

■ Missing content reasons returned in the missing content property, comr, are available in Enterprise Vault 7.0 SP3 and Enterprise Vault 2007 SP1. See “Enterprise Vault 2007 SP1, Enterprise Vault 7.0 SP3, and Enterprise Vault 6.0 SP5” on page 31.

■ The event and task properties, csrt, cend, clon, tddt, tcdt and tsts are available in Enterprise Vault 8.0 SP3 and later.

■ The shct property is not supported from Enterprise Vault 10.

Page 680: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

680 Enterprise Vault PropertiesDefined custom properties

Defined custom propertiesThe following list of custom properties are also defined in Enterprise Vault.

Note 1Format is<UTC_datetime_of_copy>,<source_archive_ID>,<source_item_Saveset_ID>

For example,2009-11-17 13:37:01Z,16B3597E77206FB4690FB46573DA6D7081110000EVServer.domain.local,200811140000000~200811141011170000~Z~B082EF701FF8FB47509D5228C99D2B51

Table B-2 Defined custom properties

Description Name Type Search-able

Retriev-able

Notes

For an item copied by Move Archive, provides the following details:

■ Time the item was copied

■ The source item archive

■ Saveset ID

Vault.CopiedFrom String See “Note 1”

If an archive has been moved several times, there will be a value for each move.

If message is a journal message, the type of journal message

Vault.JournalType String Currently defined values:

■ E2007■ E2003■ E2007ClearText

E2007RMS

See “Note 2”

Message direction Vault.MsgDirection String 32-bit integer as a string.

Currently defined values:

0 - undefined1 - internal2 - external-in3 - external-out

Type of the message. Vault.MsgType String Currently defined values:

■ EXCH■ Bloomberg■ IM.vendor■ FAX.vendor■ DXL

Page 681: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

681Enterprise Vault PropertiesDefined custom FSA properties

Note 2If the message is from Exchange Server 2010 with journal report decryption enabled, then the message is in Exchange Server 2007 report format and includes both an RMS-protected copy and a clear text copy of the message. Both copies are stored in the saveset. The advanced setting in the Enterprise Vault Exchange Journaling policy, ClearText copies of RMS Protected items, determines whether Enterprise Vault uses the clear text copy or the RMS-protected copy as the primary message during archiving. If the value of Vault.JournalType is "E2007RMS", then the primary message is the RMS-protected copy. A value of "E2007ClearText" indicates that the primary message is the clear text copy.See the Administrator’s Guide for more information on this policy setting.

Defined custom FSA properties The following list of custom properties are defined in Enterprise Vault for FSA items.

Defined custom SharePoint propertiesThe following list of custom properties are defined in Enterprise Vault for SharePoint items.

Table B-3 Defined custom FSA properties

Description Name Type Search-able

Retriev-able

Notes

Original Name of file at the point of archival

EVFSA.OriginalFileName String

Indicator that item was imported from DLM

EVFSADLMImport.DLM String Currently only

populated with

the string

"Imported"

Table B-4 Defined custom SharePoint properties

Description Name Type Seach-able

Retriev-able

Notes

Document title EVSP.Title String

SharePoint documentId EVSP.DocId String

Page 682: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

682 Enterprise Vault PropertiesDefined properties for Compliance Accelerator

Defined properties for Compliance AcceleratorThe following list of custom properties are defined in Enterprise Vault for items processed by the Compliance Accelerator Journaling Connector.

Document version EVSP.Version String

Check in comment EVSP.Comment String

Display name of document editor

EVSP.Editor String

Domain name (Windows account name) of document author

EVSP.CreatedBy String

Domain name (Windows account name) of document editor

EVSP.ModifiedBy String

SharePoint Site Id EVSP.SiteId String

SharePoint Site name EVSP.Site String

SharePoint Site Url EVSP.SiteUrl String

Customer configurable properties - any SharePoint property

EVSPP.<Sharepoint property name>

String

Table B-4 Defined custom SharePoint properties

Description Name Type Seach-able

Retriev-able

Notes

Table B-5 Defined custom properties for Journaling Connector

Description Name Type Searchable Retrievable Multi-Valued

Notes

The set of CA Department Ids that the item's author is a member of

KVSCA.DeptAuthor String CA Dept IDs

Page 683: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

683Enterprise Vault PropertiesDefined properties for Compliance Accelerator

The set of CA Department Ids that the item's recipients are members of

KVSCA.DeptRecips String CA Dept IDs

The union of KVSCA.DeptAuthor and KVSCA.DeptRecips

KVSCA.Department String CA Dept IDs

Policies, defined in the policy management software, which do not affect capture either way; they only categorize emails.

evtag.category String Policy names

Policies, defined in the policy management software, which either preclude capture or advocate non-capture.

evtag.exclusion String Policy names

Policies, defined in the policy management software, which either demand or suggest capture.

evtag.inclusion String Policy names

The policy action is the overall action that should be taken on an item; the sum result of all the applied policies.

Vault.PolicyAction String Defined values are:

■ NOACTION■ EXCLUDE■ INCLUDE

Table B-5 Defined custom properties for Journaling Connector

Description Name Type Searchable Retrievable Multi-Valued

Notes

Page 684: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

684 Enterprise Vault PropertiesDefined properties for Compliance Accelerator

Page 685: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Appendix

C

API return values

This appendix lists the Enterprise Vault API return values.

Content Management API return values

Table C-1 Content Management API return values

Return value Value Description

CONTENTMANAGEMENTAPI_E_UNAVAILABLE 0x80040300 Enterpise Vault is not running

CONTENTMANAGEMENTAPI_E_ARCHIVE_FULL 0x80040301 Time to create a new archive

CONTENTMANAGEMENTAPI_E_BUSY 0x80040302 Enterprise Vault is temporarily unable to process the request. The server is busy, or has insufficient resources, or is only able to read data due to ongoing backups. Wait and retry later.

CONTENTMANAGEMENTAPI_E_NO_ACCESS 0x80040303 Caller has insufficient permissions to access the vault store, archive, or item,or archive is in a read-only state.

CONTENTMANAGEMENTAPI_E_BAD_PARAMETER 0x80040304 Problem with input parameters

CONTENTMANAGEMENTAPI_E_AMBIGUOUS_PARAMETER 0x80040305 An input parameter identifies more than one object

CONTENTMANAGEMENTAPI_E_INTERNAL_FAILURE 0x80040306 An internal failure occurred

Page 686: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

686 API return valuesRetention API return values

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

CONTENTMANAGEMENTAPI_E_ITEM_NOT_FOUND 0x80040307 Item not found

CONTENTMANAGEMENTAPI_E_NOT_FOUND 0x80040308 Archive, Vault Store or Retention Category does not exist

CONTENTMANAGEMENTAPI_E_DELETION_BARRED 0x80040309 Deletion of the item is not permitted

CONTENTMANAGEMENTAPI_E_NO_LICENSE 0x8004020A API is not correctly licensed

CONTENTMANAGEMENTAPI_E_LICENSE_EXPIRED 0x8004030B API license has expired

CONTENTMANAGEMENTAPI_E_INVALID_DEVICE 0x8004030C Not a compliance device

CONTENTMANAGEMENTAPI_E_DUPLICATE_ITEMID 0x8004030D Attempting to insert/copy/move item with an Item Id that is not unique in the target vault store.

CONTENTMANAGEMENTAPI_E_NOT_SUPPORTED 0x8004030E The operation is not supported.

Table C-1 Content Management API return values

Return value Value Description

Table C-2 Retention API return values

Return value Value Description

RetentionCategoryAlreadyExists 0x800700b7 Returned when attempting to add a retention category, and one already exists with the same name.

RetentionCategoryNotExist 0x80070002 Returned when attempting to update a retention category, and the RetentionCategoryId does not exist in the Enterprise Vault directory.

SiteIdNotFound 0x800704BA Returned if the site specified by DirectoryDNSAlias does not exist.

Page 687: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

687API return valuesSearch API return values

le

g

x

x

Search API return valuesThe following return values are defined for the Search API:

Table C-3 Search API return values

Return value Value Description

rvS_OK 0x00000000 Successful completion

rvS_FALSE 0x00000001 Sucessful - but the input data or output data is empty

rvE_POINTER 0x80004003 An invalid or NULL pointer argument

rvE_INVALIDARG 0x80070057 Invalid argument

rvE_ACCESSDENIED 0x80070005 Caller has insufficient permissions to access an index

rvE_NOINTERFACE 0x80004002 Interface is not support or not valid

rvE_SERVER_UNAVAILABLE 0x800706BA The index server is not currently availab

rvINDEXING_W_ARCHIVE_NOT_SET 0x80041C6B An archive has not been selected

rvINDEXING_W_CANT_ACCESS_DIRECTORY 0x80041C11 The Enterprise Vault Directory is not available

rvINDEXING_E_ARCHIVE_NOT_FOUND 0xc0041C5C The archive does not exist

rvINDEXING_W_INDEXDISABLED 0x80041C84 The archive's index is current disabled

rvINDEXING_W_ARCHIVE_BEING_DELETED 0x80041C52 The archive is marked for deletion

rvINDEXING_W_UNKNOWN_INDEX_VOLUME_SET 0x80041C6C The index volume set identity does not belong to the currently selected archive

rvINDEXING_W_UNKNOWN_INDEX_VOLUME 0x80041C6D The index volume identity does not belonto the currently selected archive

rvINDEXING_W_UNABLE_FAILED_VOLUME 0x80041C69 The search failed due to at least one indevolume being marked as failed

rvINDEXING_W_UNABLE_OFFLINE_VOLUME 0x80041C6A The search failed due to at least one indevolume being marked as offline

rvINDEXING_E_TOO_MANY_RESULTS 0xc0041C83 The search request was rejected because too many search results were requested. The maximum is defined by the MaxSearchResultsPerVolumeSet property.

Page 688: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

688 API return valuesExternal Filter API Event log messages

x

x

x

e

.

h s

External Filter API Event log messagesThe following events are written to the Enterprise Vault event log by the Task Filter Controller.

rvINDEXING_E_TOO_MANY_VOLUMES 0xc0041C82 The search request was rejected because there are too many index volumes to search. The maximum is defined by the MaxSearchIndexVolumeSets property.

rvINDEXING_W_SERVICE_BUSY 0x80041C86 The search was rejected because the indexing service is too busy

rvINDEXING_W_SERVER_STOPPING 0x80041C1A The search was rejected because the indeis being unloaded to allow another indexto be searched

rvINDEXING_W_SERVICE_STOPPING 0x80041C47 The search was rejected because the indeservice is being shutdown

rvINDEXING_W_SEARCH_WOULD_BLOCK 0x80041C70 The search was rejected because the indeis currently overloaded with search requests

rvINDEXING_W_SEARCH_TIMEDOUT 0x80041C71 The search failed because it took too longto complete. The timeout is defined by thTimeout property.

rvINDEXING_E_INVALID_QUERY 0xC0041C53 The search was rejected since the searchquery was invalid.

rvINDEXING_E_ILLEGAL_WILDCARD_QUERY 0xC0041C5E The search was rejected since the searchquery contained invalid wildcard terms.

rvINDEXING_E_FAILED_SEARCH_REQUEST 0xC0041C67 The search failed due to an internal errorCheck the Enterprise Vault event log on the Enterprise Vault server.

rvINDEXING_E_INDEX_SEARCH_FAILED 0xC0041C0E The search failed due to a failure to searcone or more of the targeted index volumesets.

Table C-3 Search API return values

Return value Value Description

Page 689: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

689API return valuesExternal Filter API Event log messages

Exchange Server filteringThe following messages are written to the Enterprise Vault event log by the Exchange Task Filter Controller.

Event Type Description Example

3144 Error Logged by the filter controller if one or more of the registered external filters fails to load, or fails to initialize.

Failed whilst initializing the Filter Controller. The agent will now shut down as it cannot reliably continue.

Error: <error information>

3263 Error Logged by the filter controller when an external filter returns an error when processing a message. (The filter’s ProcessFilter method returns a non-zero return value). The filter controller stops processing the message.

An error occurred processing the external filter '<filter prog id>'. No more filters will be processed.

Error: <error information>Mailbox: <mailbox DN>Message Folder: <folder name>Message Title: <message title>

3146 Error Logged by the filter controller when attempting to create an instance of an external filter.

Failed to initialize the external filter with ProgId '<filter prog id>'. Either the ProgId is incorrect or the DLL has not been registered.

Please check the ProgId or register the DLL for the external filter.

3147 Error Logged by the filter controller when an external filter returns an error when initializing. (The filter’s Initialize method returns a non-zero return value).

An error has occurred initializing the external filter '<filter prog id>'.

Error: <error information>

3150 Error Logged by the filter controller when a stream of consecutive errors are encountered.

Whilst processing external filters too many consecutive errors have occurred. This Task will now shut down.

45329 Informational Logged by the filter controller at the point of initializing each external filter.

External Filter '<filter prog id>' initializing...

45330 Informational Logged by the filter controller at the point of stopping each external filter.

External Filter '<filter prog id>' stopped.

Page 690: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

690 API return valuesExternal Filter API Event log messages

Domino Server filteringThe following messages are written to the Enterprise Vault event log by the Domino Journaling Task Filter Controller.

Event Type Description Example

41086 Informational Logged by the filter controller at the point of initializing each installed filter plug-in.

The Domino external filter ‘<filter_name>’ has started.

41087 Informational Logged by the filter controller at the point of de-initializing each installed filter plug-in.

The Domino external filter ‘<filter_name>’ has stopped.

41088 Error Logged by the filter controller if a filter plug-in raises an error during processing. The reason for the error is contained in the message text.

The Domino external filter '<filter_name>' failed to process an item.

Reason: An applicable RuleSet has not been defined for database 'symantec\db_name.nsf' and a default Content Category has not been specified.

41036 Error Logged by the filter controller if a filter plug-in raises an error during initialization. The reason for the error is contained in the message text.

Unable to start the FilterController The following error occurred:

Unable to initialize() filter '<filter_name>'.

Reason: ...

Page 691: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

Index

AAddProperty method

ISearchQuery interface methodsSearchQuery object 552

AddQuery methodISearchQuery interface methods

SearchQuery object 558

Ccompressing items 517constants

ESearchQueryFlags constantSearch API 533

Converting items 517Custom Filtering API

get_defaultRetentionCategoryId methodsIArchivingControl interface 445

ProcessFilter methodIExternalFilter interface 437

EEnterprise Vault documentation 15ESearchQueryFlags constant

Search API 533

Fflags

ESearchQueryFlags constantSearch API 533

Gget_defaultRetentionCategoryId methods

IArchivingControl interfaceCustom Filtering API 445

IIndexes

updating 517

Indexing items 517Indexing levels 517IndexSearch2 object

Search APISelectArchive method 588

interface methodsAddProperty

SearchQuery object 552AddQuery

SearchQuery object 558SelectArchive

IndexSearch2 object 588SetProperty

SearchQuery object 550ISearchQuery interface methods

AddProperty method 552AddQuery method 558SetProperty method 550

itemscompressing 517converting 517

Mmethods

SelectArchiveIndexSearch2 object 588

PProcessFilter method

IExternalFilter interfaceCustom Filtering API 437

SSearch API

ESearchQueryFlags constant 533searches

overview of performing a search 524results, processing 527

SearchQuery objectSearchQuery interface methods

Page 692: Symantec Enterprise Vault - Talented Teacher Jobs · 2017-07-15 · Symantec Enterprise Vault: Application Programmer’s Guide The software described in this book is furnished under

692 Index

AddProperty 552AddQuery 558SetProperty 550

SelectArchive methodIndexSearch2 object

Search API 588SetProperty method

ISearchQuery interface methodsSearchQuery object 550


Recommended