IDSSDashboardTemplate Interface Reference

List of all members.

---

Detailed Description

A DSS Object that records information about a way to create a DSS Document Definition.

The document is created by importing data from some data source and then creating a new document definition made by reconciling an existing document definition to the new data. The existing definition could be located in this project, or could take the form of a project package file.

Public Member Functions
HRESULT	AddAnnotation ([in] BSTR iTextKey,[in, defaultvalue(NULL)] IDSSObjectReference *ipObjectReference,[in, defaultvalue(NULL)] IDSSObjectReference *ipSecondaryReference,[out, retval] IDSSAnnotation oppAnnotation)
	Add a annotation identified by an arbitrary string and an object reference.
HRESULT	AnnotationCount ([out, retval] Int32 *opCount)
	Get the count of annotations.
HRESULT	AnnotationItemByIndex ([in] Int32 iIndex,[out, retval] IDSSAnnotation oppAnnotation)
	Get the annotation at certain index.
HRESULT	AnnotationItemByKey ([in] BSTR iTextKey,[in, defaultvalue(NULL)] IDSSObjectReference *ipObjectReference,[in, defaultvalue(NULL)] IDSSObjectReference *ipSecondaryReferenceKey,[out, retval] IDSSAnnotation oppAnnotation)
	Get the annotation for a certain key.
HRESULT	GetFinalDocumentAndRelatedObjects ([in, defaultvalue(NULL)] IDSSUserRuntime *ipUserRuntime,[out, retval] IDSSObjectContext oppDocumentAndRelatedObjects)
	Get a fresh document definition and related objects (e.g.
HRESULT	Info ([out, retval] IDSSObjectInfo ppInfo)
	Shortcut to IDSSObjectInfo interface to this Dashboard object.
HRESULT	MapReference ([in] IDSSObjectReference *ipSearchReference,[in] IDSSObjectReference *ipReplaceReference)
	Map references to one object with references to another object.
HRESULT	Original ([in] IDSSObjectInfo *ipOriginal)
	Get the object on which this template is based.
HRESULT	Original ([out, retval] IDSSObjectInfo oppOriginal)
	Get the object on which this template is based.
HRESULT	ReconcileManifest ([in] IDSSSourceManipulatorCallBack *ipCallback,[in, defaultvalue(NULL)] IDSSUserRuntime *ipUserRuntime)
	Get the quick reconciliation manifest used by this document template.
HRESULT	RemoveAnnotation ([in] VARIANT *ipIndex)
	Remove the identified annotation from the collection.
HRESULT	Thumbnail ([in] IDSSBlob *ipThumbnailBlob)
	Set the thumbnail as a blob object.
HRESULT	Thumbnail ([out, retval] IDSSBlob oppThumbnailBlob)
	Get the thumbnail as a blob object.
HRESULT	ThumbnailID ([in] BSTR iThumbnailBlobID)
	Set the thumbnail as an ID of a blob object.
HRESULT	ThumbnailID ([out, retval] BSTR *opThumbnailBlobID)
	Get the thumbnail as an ID of a blob object.
HRESULT	ThumbnailString ([in] BSTR iThumbnailString)
	Set the thumbnail as a monolingual string (presumably a file name).
HRESULT	ThumbnailString ([out, retval] BSTR *opThumbnailString)
	Get the thumbnail as a monolingual string (presumably a file name).

---

Member Function Documentation

HRESULT IDSSDashboardTemplate::AddAnnotation (  [in] BSTR  iTextKey, [in, defaultvalue(NULL)] IDSSObjectReference *  ipObjectReference, [in, defaultvalue(NULL)] IDSSObjectReference *  ipSecondaryReference, [out, retval] IDSSAnnotation   oppAnnotation )

Add a annotation identified by an arbitrary string and an object reference. If an annotation already exists that uses the given key then it will be returned. Parameters: iTextKey  The string used to identify the annotation. Any string, including empty string, will be accepted. NULL will be interpretted as the same as empty string. String comparison is performed in a case sensitive manner. ipObjectReference  The object, if any, used to identify this annoation. We use an object reference so that it is not necessary to load the object. Indeed the object is not required to actually exist at all (and is not a reference). ipSecondaryReference  The secondary object, if any, used to identify this annotation. This is intended to be used to permit annotations for a form within an attribute. The form would be the primary object, the attribute would be the secondary object. oppAnnotation  The annotation identified by the key parameters. It counld be a new one added or an existing one. Returns: Usual COM result code. S_OK E_INVALIDARG iTextKey was NULL (or empty string) and ipObjectReference was also NULL.

HRESULT IDSSDashboardTemplate::AnnotationCount (  [out, retval] Int32 *  opCount  )

Get the count of annotations. Parameters: opCount  The count of annotations. Returns: Usual COM result code.

HRESULT IDSSDashboardTemplate::AnnotationItemByIndex (  [in] Int32  iIndex, [out, retval] IDSSAnnotation   oppAnnotation )

Get the annotation at certain index. This method is used to iterate over all the annotations in a document template. Parameters: iIndex  Index number between 1 and AnnotationCount oppAnnotation  Return pointer to the annotation. Returns: Usual COM result code: S_OK DSSCOM_E_INDEX_OUT_OF_RANGE ipIndex was number, but not in correct range.

HRESULT IDSSDashboardTemplate::AnnotationItemByKey (  [in] BSTR  iTextKey, [in, defaultvalue(NULL)] IDSSObjectReference *  ipObjectReference, [in, defaultvalue(NULL)] IDSSObjectReference *  ipSecondaryReferenceKey, [out, retval] IDSSAnnotation   oppAnnotation )

Get the annotation for a certain key. The key is a string and (optionally) an object reference. Parameters: iTextKey  The string used to identify the annotation. Any string, including empty string, will be accepted. NULL will be interpretted as the same as empty string. String comparison is performed in a case sensitive manner. ipObjectReference  The object, if any, used to identify this annoation. We use an object reference so that it is not necessary to load the object. Indeed the object is not required to actually exist at all (and is not a reference). ipSecondaryReferenceKey  The secondary object, if any, used to identify this annotation. This is intended to be used to permit annotations for a form within an attribute. The form would be the primary object, the attribute would be the secondary object. oppAnnotation  Return pointer to the annotation. Returns: Usual COM result code: S_OK E_INVALIDARG iTextKey was NULL (or empty string) and ipObjectReference was also NULL. DSSCOM_E_KEY_NOT_FOUND No existing annotation matches the given key.

HRESULT IDSSDashboardTemplate::GetFinalDocumentAndRelatedObjects (  [in, defaultvalue(NULL)] IDSSUserRuntime *  ipUserRuntime, [out, retval] IDSSObjectContext   oppDocumentAndRelatedObjects )

Get a fresh document definition and related objects (e.g. derived elements) based on this document template. Behind the scenes, the original dependencies of the document definition are replaced by objects set up by MapReference. The object returned will always have a fresh ID. Parameters: oppDocumentAndRelatedObjects  The output object context containing the RWD and related objects (e.g. derived elements) ipUserRuntime  The user runtime. Returns: Usual COM result code. CLISVC_E_UNEXPECTED_REPLACE_REFERENCE One of the replacement objects set up by MapReference is equal to one of the original dependencies of the RWD.

HRESULT IDSSDashboardTemplate::Info (  [out, retval] IDSSObjectInfo   ppInfo  )

Shortcut to IDSSObjectInfo interface to this Dashboard object. The IDSSObjectInfo interface to this object. Returns: Usual COM result code: S_OK

HRESULT IDSSDashboardTemplate::MapReference (  [in] IDSSObjectReference *  ipSearchReference, [in] IDSSObjectReference *  ipReplaceReference )

Map references to one object with references to another object. It's used to replace references to objects the RWD originally depends on with references to objects in the destination project. We will not permit an object that is a dependency of the RWD to be a replace object. Nor will we permit any object to be used more than once as either a search or a replacement object. An attempt to reuse an object should be rejected at set up time. An attempt to use an object that is a dependency of the RWD will be detected when GetFinalDocumentAndRelatedObjects is called, and will return an error at that time. This is to prevent the risk of introducing duplications within the RWD which would cause the object to be rejected by engine. (Here we are thinking of cases like replacing an attribute on a template with another attribute which is already on the template – such a replacement would be forbidden because we would require that the replacement attribute is unknown to the RWD, and so cannot have already have been on the template). This method does not cause a change in the serializable state of the DSS Document Template. That is the reference mapping is not saved or copied when a document template is savied or copied. Nevertheless this method does change the in-memory state of a DSS Document Template, and as such may not be called on a read-only instance of the object, such as one returned from the object server cache. Parameters: ipSearchReference  The object reference to find. ipReplaceReference  Use this object reference to replace the one found. Returns: Usual COM result code. CLISVC_E_REPEATED_MAP_REFERENCE ipSearchReference or ipReplaceReference is set up more than once. DSSCOM_E_PROHIBITED_WRITE Attempt made to call this method on a read-only instance.

HRESULT IDSSDashboardTemplate::Original (  [in] IDSSObjectInfo *  ipOriginal  )

Get the object on which this template is based. The object could be a document definition object, or a blob object. In the latter case the blob should contain a package file that contains the original document definition object.

HRESULT IDSSDashboardTemplate::Original (  [out, retval] IDSSObjectInfo   oppOriginal  )

Get the object on which this template is based. The object could be a document definition object, or a blob object. In the latter case the blob should contain a package file that contains the original document definition object.

HRESULT IDSSDashboardTemplate::ReconcileManifest (  [in] IDSSSourceManipulatorCallBack *  ipCallback, [in, defaultvalue(NULL)] IDSSUserRuntime *  ipUserRuntime )

Get the quick reconciliation manifest used by this document template. Parameters: ipCallback  The callback interface to process the manifest. ipUserRuntime  The user runtime. Returns: Usual COM result code.

HRESULT IDSSDashboardTemplate::RemoveAnnotation (  [in] VARIANT *  ipIndex  )

Remove the identified annotation from the collection. Parameters: ipIndex  Variant value to describe the desired member. Possibilities are: Integer: Index number between 1 and Count Pointer: An interface reference (IDSSAnnotation) identifying the annotation. Returns: Usual COM result code: S_OK E_INVALIDARG ipIndex was NULL. DSSCOM_E_INDEX_OUT_OF_RANGE ipIndex was number, but not in correct range. DSSCOM_E_NOTFOUND ipIndex was a pointer, but no annotation found. DSSCOM_E_BAD_ITEM_SPEC ipIndex was wrong type of Variant.

HRESULT IDSSDashboardTemplate::Thumbnail (  [in] IDSSBlob *  ipThumbnailBlob  )

Set the thumbnail as a blob object. We expect the blob object contains a small image. Note that using this property requires that the blob object should be loaded into memory. Since blob objects are typically large, this property should only be used if the blob object would have been used in any case. Use Thumbnail to change which blob object is referenced without loading the blob object.

HRESULT IDSSDashboardTemplate::Thumbnail (  [out, retval] IDSSBlob   oppThumbnailBlob  )

Get the thumbnail as a blob object. We expect the blob object contains a small image. Note that using this property requires that the blob object should be loaded into memory. Since blob objects are typically large, this property should only be used if the blob object would have been used in any case. Use Thumbnail to change which blob object is referenced without loading the blob object.

HRESULT IDSSDashboardTemplate::ThumbnailID (  [in] BSTR  iThumbnailBlobID  )

Set the thumbnail as an ID of a blob object. We expect the blob object contains a small image. This property returns a blob reference as an ID. It should be used if the caller wishes to identify which blob object is referenced without loading the blob object. Note that even if the caller identifies the blob object as an ID, the object is stored using a normal reference. Thus setting this property will cause a blob object to appear as a dependent of the document template.

HRESULT IDSSDashboardTemplate::ThumbnailID (  [out, retval] BSTR *  opThumbnailBlobID  )

Get the thumbnail as an ID of a blob object. We expect the blob object contains a small image. This property returns a blob reference as an ID. It should be used if the caller wishes to identify which blob object is referenced without loading the blob object. Note that even if the caller identifies the blob object as an ID, the object is stored using a normal reference. Thus setting this property will cause a blob object to appear as a dependent of the document template.

HRESULT IDSSDashboardTemplate::ThumbnailString (  [in] BSTR  iThumbnailString  )

Set the thumbnail as a monolingual string (presumably a file name). The input string must not in a form of a GUID (e.g. DC511DA0494B02FBB17575A53B62D0A1). And its length must not exceeds 250 characters.

HRESULT IDSSDashboardTemplate::ThumbnailString (  [out, retval] BSTR *  opThumbnailString  )

Get the thumbnail as a monolingual string (presumably a file name). The form of the string will never in a form of a GUID (e.g. DC511DA0494B02FBB17575A53B62D0A1). And its length won't exceeds 250 characters.

---