The Initialize method is used to configure the Add operation, including providing the client with the ability to customize the dialog title. This method also enables the client to specify information about the item to be added, such as the name and directory location of the file on the local machine, the XML for the item properties, and the relationship to establish between the item being added and other items that have already been added to the object store.
When Records Manager is enabled for the Application Engine, the Initialize
method can be used to specify whether the Declare Record operation should be
made available for the specified object store. If the object store has the Records
Manager feature enabled, and the bDeclareRecordOn
parameter is set to VARIANT_TRUE
, then the DeclareRecord
button will be visible on the Confirmation page of the Add Wizard. The user
can then click DeclareRecord to execute the Declare
Record operation.
The Declare Record operation will be executed on every document represented
by an ID in the vDocumentIDs
parameter, including the
newly added document. If the vDocumentIDs
parameter
is empty, the operation will only be performed on the new document. If the bDeclareRecordOn
parameter is set to VARIANT_FALSE
, the vDocumentIDs
parameter will be ignored and the DeclareRecord
button will not be visible.
NOTE When Records Manager is not enabled for the
Application Engine or the object store does not have the Records Manager
feature enabled, both the bDeclareRecordOn
and vDocumentIDs
parameters will be ignored. However, if Workplace determines that the Declare
Record operation must be made available, then the DeclareRecord
button will be visible.
void spIAddCmd->Initialize(_bstr_t bstrDialogTitle, _bstr_t bstrPathName, _bstr_t bstrRootDocClass, VARIANT_BOOL bRestrictClass, _bstr_t bstrPropertiesXml, VARIANT vLinkDescriptors, VARIANT_BOOL bDeclareRecordOn, VARIANT vDocumentIDs);
bstrDialogTitle
- [in] Required _bstr_t, which specifies
the label to display in the title bar of the Add Wizard dialog when the Add
command is invoked. By using this parameter, client applications can customize
the title that appears at the top of the Wizard dialog to correspond with
their application requirements.bstrPathName
- [in] Required _bstr_t, which specifies
the name and directory location of the file on the local machine that is to
be added.bRestrictClass
- [in] Required VARIANT_BOOL, which
represents the class ID(s) that should be made available for selection and
use by the Add operation. This parameter can be set to the following:VARIANT_TRUE
, only allow the root document class ID specified
in bstrRootDocClass to be selected.VARIANT_FALSE
, allow the root document class ID specified
in bstrRootDocClass or any of its' children to be selected.NOTE: When bstrRootDocClass is empty,
only the base Document class may be selected, regardless of whether bRestrictClass
has been set to true or false.
bstrPropertiesXml
- [in] Required _bstr_t, the XML
which specifies the properties to apply to the item during the Add operation,
where the XML must be of the form:
<properties>
<property>
<symname>SymbolicName</symname>
<values>
<value>PropertyValue</value>
<value>...</value></values>
</property>
<property>
...
</property>
</properties>
vLinkDescriptors
- [in] Required pointer to a VARIANT,
which contains a SAFEARRAY of LinkDescriptor
components that specify the links to be established between the item being
added and other (already existing) items in the object store. Each
ILinkDescriptor represents a linked object to be created. When no links
are required, a value of VT_EMPTY
should be specified.bDeclareRecordOn
- [in] Required VARIANT_BOOL, which
represents whether the DeclareRecord button
should be visible on the Confirmation page of the Add Wizard. This parameter
can be set to the following:VARIANT_TRUE
, the DeclareRecord
button will be visible. VARIANT_FALSE
, the DeclareRecord
button will not be visible.vDocumentIDs
- [in] Required pointer to a VARIANT,
which contains a SAFEARRAY of the IDs (GUIDs) for the documents which already
exist in the specified object store. If the object store does not yet contain
any documents, a value of VT_EMPTY
should be specified. NOTE
This parameter is ignored when the bDeclareRecordOn
parameter is set to false.... // Create the LinkDescriptors for the item to Add const DWORD cNumElements = 2; long lCount = 0; COleSafeArray saLinks(VT_DISPATCH, cNumElements); { // Instantiate a LinkDescriptor component
ILinkDescriptorPtr spILinkDescriptor0(__uuidof(LinkDescriptor)); _ASSERTE(spILinkDescriptor != 0); // Instantiate the ObjectStoreItem component IObjectStoreItemPtr spIObjectStoreItem0; hResult = spIObjectStoreItem0.CreateInstance(__uuidof(ObjectStoreItem));
if (FAILED(hResult)) {
std::cout << "Could not create the ObjectStoreItem component.\n"; _ASSERTE(0);
} // Initialize the ObjectStoreItem component with // the items' type, name, version series ID and version ID. ItemType eItemType = eItemTypeDocument; _bstr_t bstrObjectStoreName = (_T("Alaska")); _bstr_t bstrVersionSeriesID = (_T("{6BC064A2-2D58-4B0A-AEF2-B2F8A1100000}")); _bstr_t bstrVersionID = (_T("{DDE54469-36D9-4fe9-8676-445E4994DE1F}")); std::cout << "Initializing the ObjectStoreItem component..." << std::endl;
spIObjectStoreItem0->Initialize(eItemType, bstrObjectStoreName, bstrVersionSeriesID, bstrVersionID); _bstr_t bstrLinkClassID = (_T("{C91111A9-CE9C-43e6-8548-8A08F43F9726}")); RelationshipType enLinkType = eTypeLinkTo; // Define the XML properties for the item to Link std::cout << "Defining the XML item properties..." << std::endl; _bstr_t bstrLinkPropertiesXml = _T( "" ); bstrLinkPropertiesXml += _T("<properties>");
bstrLinkPropertiesXml += _T("<property>");
bstrLinkPropertiesXml += _T("<symname>DocumentTitle</symname>"); bstrLinkPropertiesXml += _T("<values>");
bstrLinkPropertiesXml += _T("<value>LinkedDocument.doc</value></values>");
bstrLinkPropertiesXml += _T("</property>");
bstrLinkPropertiesXml += _T("<property>");
bstrLinkPropertiesXml += _T("<symname>CommentReq</symname>"); bstrLinkPropertiesXml += _T("<values>");
bstrLinkPropertiesXml += _T("<value>This will be a linked document.</value></values>");
bstrLinkPropertiesXml += _T("</property>");
bstrLinkPropertiesXml += _T("<property>");
bstrLinkPropertiesXml += _T("<symname>SVCPStr</symname>"); bstrLinkPropertiesXml += _T("<values>");
bstrLinkPropertiesXml += _T("<value>This is the SVCPStr property</value></values>");
bstrLinkPropertiesXml += _T("</property>");
bstrLinkPropertiesXml += _T("</properties>"); // Initialize the LinkDescriptor component to hold the link std::cout << "Initializing LinkDescriptor component 1..." << std::endl; spILinkDescriptor0->Initialize(spIObjectStoreItem0, bstrLinkClassID, enLinkType, bstrLinkPropertiesXml); if(spILinkDescriptor0) { saLinks.PutElement(&lCount, spILinkDescriptor0); } } { lCount++; // Instantiate a LinkDescriptor component
ILinkDescriptorPtr spILinkDescriptor1(__uuidof(LinkDescriptor)); _ASSERTE(spILinkDescriptor != 0); // Instantiate the ObjectStoreItem component IObjectStoreItemPtr spIObjectStoreItem1; hResult = spIObjectStoreItem1.CreateInstance(__uuidof(ObjectStoreItem));
if (FAILED(hResult)) {
std::cout << "Could not create the ObjectStoreItem component.\n"; _ASSERTE(0);
} // Initialize the ObjectStoreItem component with // the items' type, name, version series ID and version ID. ItemType eItemType = eItemTypeDocument; _bstr_t bstrObjectStoreName = (_T("Alaska")); _bstr_t bstrVersionSeriesID = (_T("{2400406D-68FE-4d5c-81FD-AC01F7186119}")); _bstr_t bstrVersionID = (_T("{6D770D89-497C-40be-B300-E646FC12DE8A}")); std::cout << "Initializing the ObjectStoreItem component..." << std::endl;
spIObjectStoreItem1->Initialize(eItemType, bstrObjectStoreName, bstrVersionSeriesID, bstrVersionID); _bstr_t bstrLinkClassID = (_T("{C91111A9-CE9C-43e6-8548-8A08F43F9726}")); RelationshipType enLinkType = eTypeLinkTo; // No XML properties for this Link item _bstr_t bstrLinkPropertiesXml = VT_EMPTY; // Initialize the LinkDescriptor component to hold the link std::cout << "Initializing LinkDescriptor component 2..." << std::endl; spILinkDescriptor1->Initialize(spIObjectStoreItem1, bstrLinkClassID, enLinkType, bstrLinkPropertiesXml); if(spILinkDescriptor1) { saLinks.PutElement(&lCount, spILinkDescriptor1); } } _variant_t vLinkDescriptors(saLinks); // Define the XML properties for the item to Add std::cout << "Defining the XML item properties..." << std::endl; _bstr_t bstrPropertiesXml = _T( "" ); bstrPropertiesXml += _T("<properties>");
bstrPropertiesXml += _T("<property>");
bstrPropertiesXml += _T("<symname>DocumentTitle</symname>"); bstrPropertiesXml += _T("<values>");
bstrPropertiesXml += _T("<value>AddedDocument.doc</value></values>");
bstrPropertiesXml += _T("</property>");
bstrPropertiesXml += _T("<property>");
bstrPropertiesXml += _T("<symname>CommentReq</symname>"); bstrPropertiesXml += _T("<values>");
bstrPropertiesXml += _T("<value>This document contains new information to be added.</value></values>");
bstrPropertiesXml += _T("</property>");
bstrPropertiesXml += _T("<property>");
bstrPropertiesXml += _T("<symname>SVCPStr</symname>"); bstrPropertiesXml += _T("<values>");
bstrPropertiesXml += _T("<value>This is the SVCPStr property</value></values>");
bstrPropertiesXml += _T("</property>");
bstrPropertiesXml += _T("</properties>");// Initialize the custom Add command component with the dialog title, // name and directory location of the file on the local machine, // a specific root document class ID, the class ID choice restriction, // as well as the XML properties and LinkDescriptors. _bstr_t bstrDialogTitle = (_T("Customized Add Operation")); _bstr_t bstrPathName = (_T("C:\Temp\DocumentToBeAdded.doc")); _bstr_t bstrRootDocClass = (_T("{379B665E-1BBA-4BEA-AA4A-BE678369F2CC}")); VARIANT_BOOL bRestrictClass = VARIANT_TRUE; VARIANT_BOOL bDeclareRecordOn = VARIANT_FALSE; _variant_t vDocumentIDs(); std::cout << "Initializing the Add command component..." << std::endl; spIAddCmd->Initialize(bstrDialogTitle, bstrPathName, bstrRootDocClass, bRestrictClass, bstrPropertiesXml, vLinkDescriptors, bDeclareRecordOn, vDocumentIDs); ...