symantec enterprise vault - talented teacher jobs · 2017-07-15 · symantec enterprise vault:...

of 692/692
Symantec Enterprise Vault Application Programmer’s Guide Enterprise Vault 9.0 SP1

Post on 17-Mar-2020

29 views

Category:

Documents

0 download

Embed Size (px)

TRANSCRIPT

  • Symantec Enterprise Vault™

    Application Programmer’s Guide

    Enterprise Vault 9.0 SP1

  • Symantec Enterprise Vault: Application Programmer’s Guide

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

    Last updated: November 19, 2010.

    Legal 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

    http://www.symantec.com

  • 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

    http://go.symantec.com/step

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

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

    mailto:[email protected]

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

  • 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

  • 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

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

  • 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

  • 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

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

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

  • 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

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

    http://msdn.microsoft.com/en-us/library/aa379570.aspx

  • 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

  • 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

  • 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

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

  • 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 element. See Table B-1 on page 664.

    Enterprise Vault 7.0 SP3, Enterprise Vault 2007 SP1

  • 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, ":", 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

  • 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

  • 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

  • 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

  • 36 API updatesEnterprise Vault 7.0

  • Chapter

    3

    Enterprise Vault API overview

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

    Overview of Enterprise Vault 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.

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

  • 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

  • 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

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

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

  • 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 entries for each of the Enterprise Vault API components used by the application.

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

    See “Updating binding redirections in configuration files”.

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