#include <ICusDtLnkFacade.h>

Inheritance diagram for ICusDtLnkFacade:

Public Types
enum	{ kDefaultIID = IID_ICUSDTLNKFACADE }

Public Member Functions
virtual ErrorCode	SetKeyValuePair (const IWorkspace *ws, const PMString &key, const PMString &val, const PMIID &iid)=0

virtual PMString	GetValueFromKey (const IWorkspace *ws, const PMString &key, const PMIID &iid) const =0

virtual bool16	IsOurCustomDataLink (const ClassID &classID) const =0

virtual bool16	IsOurCustomDataLink (const UIDRef &linkUIDRef) const =0

virtual ErrorCode	AddAdornment (const UIDList &itemList)=0

virtual ErrorCode	RemoveAdornment (const UIDList &itemList)=0

virtual ErrorCode	AddAssetDataBase (const IWorkspace *ws, const PMString &dbName, const PMString &fullPath)=0

virtual PMString	GetNthAssetDataBase (const IWorkspace *ws, int32 index) const =0

virtual int32	GetAssetDataBaseCount (const IWorkspace *ws) const =0

virtual PMString	GetAssetDataBasePath (const IWorkspace *ws, const PMString &dbName) const =0

virtual PMString	TruncatePath (const PMString &fullPath, bool16 useAnySeparator=kTrue, const PlatformChar &useThisOne=kTextChar_Solidus) const =0

virtual UIDRef	ImportImageAndLoadPlaceGun (const UIDRef &docUIDRef, const PMString &path, const PMString &uniqueKey)=0

virtual UIDRef	ImportImageAndLoadPlaceGun (const UIDRef &docUIDRef, const URI &uri)=0

virtual PMString	GetCurrentlyChosenUniqueAssetKey (const IWorkspace *ws) const =0

virtual ErrorCode	SetCurrentlyChosenUniqueAssetKey (const IWorkspace *ws, const PMString &newKey)=0

virtual ErrorCode	InitializeDataLink (const IWorkspace ws, IDataLink dl, const IDFile &file, const PMString &formatName, const PMString &uniqueAssetKey)=0

virtual bool	UniqueKeyToURI (const PMString &uk, URI &uri) const =0

virtual bool	URIToIDFile (const URI &uri, IDFile &file) const =0

virtual PMString	GetFirstPartOfPath (const PMString &p) const =0

virtual IDFile	GetLocalFileFromAssetIdentifier (const IWorkspace *ws, const PMString &uniqueAssetKey) const =0

virtual PMString	GetAssetDataBaseRecordFieldValue (const IDFile &databaseFile, const PMString &recordID, const PMString &fieldName) const =0

virtual uint64	GetAssetSizeFromAssetIdentifier (const IWorkspace *ws, const PMString &uniqueAssetKey) const =0

virtual uint64	GetAssetTimestampFromAssetIdentifier (const IWorkspace *ws, const PMString &uniqueAssetKey) const =0

virtual PMString	GetAssetDescriptionFromAssetIdentifier (const IWorkspace *ws, const PMString &uniqueAssetKey) const =0

virtual uint64	GetAssetTimestampFromURI (const URI &uri) const =0

virtual PMString	GetFieldValueFromAssetIdentifier (const IWorkspace *ws, const PMString &uniqueAssetKey, const PMString &fieldName) const =0

virtual PMString	GetAssetDescriptionFromURI (const URI &uri) const =0

virtual void	StoreUniqueKey (IDataLink *dataLink, const PMString &uniqueAssetKey)=0

virtual PMString	RetrieveUniqueKey (IDataLink *dataLink) const =0

PMString	GetRecordFieldValueFromURI (const URI &uri, PMString &whichField) const

virtual bool16	NeedsOurAdornment (const UIDRef &pageItemUIDRef) const =0

virtual bool16	HasOurAdornment (const UIDRef &pageItemUIDRef) const =0

Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0

virtual void	AddRef () const =0

virtual void	Release () const =0

Detailed Description

From SDK sample; facade interface that is used by both this plug-in and it's associated UI, CustomDataLinkUI sample. Provides methods to access and store persistent data, including the database files used by this sample. Also provides methods to work with the adornments added to the containers for custom datalinked layout objects.

See Also: CustomDataLinkUI

Member Enumeration Documentation

anonymous enum

Default interface identifier for UseDefaultIID

See Also: UseDefaultIID

Member Function Documentation

virtual ErrorCode ICusDtLnkFacade::AddAdornment ( const UIDList & itemList )

pure virtual

Add our page item adornment to the list of layout objects

Parameters

itemList specifies layout objects to add adornment to

Returns: ErrorCode kSuccess if we succeeded, another ErrorCode otherwise

Implemented in CusDtLnkFacade.

virtual ErrorCode ICusDtLnkFacade::AddAssetDataBase	(	const IWorkspace *	ws,
		const PMString &	dbName,
		const PMString &	fullPath
	)

pure virtual

Add a mapping from database name to where the database file is in the local filesystem, persisting this to the session workspace.

Parameters

dbName	the database name, e.g. alias-database-1.csv
fullPath	where the database file is located in the local file system

Returns: ErrorCode kSuccess if we succeeded, another ErrorCode otherwise

Implemented in CusDtLnkFacade.

virtual int32 ICusDtLnkFacade::GetAssetDataBaseCount ( const IWorkspace * ws ) const

pure virtual

Determine how many databases are known about, that is, mapped through to database files in the local filesystem

Returns: int32 giving number of databases for which we have done an AddAssetDataBase and where we know what the path is to the database file given its name

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetAssetDataBasePath	(	const IWorkspace *	ws,
		const PMString &	dbName
	)		const

pure virtual

Given a name of a database, e.g. alias-database-1.csv, return a path to the database file in local filesystem as PMString

Parameters

dbName identifies the database, found in the custom datalink as first part of the unique asset key for a custom datalink

Returns: PMString with path to the database file in local filesystem

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetAssetDataBaseRecordFieldValue	(	const IDFile &	databaseFile,
		const PMString &	recordID,
		const PMString &	fieldName
	)		const

pure virtual

Given a database (a flatfile database with a single, unnamed table) and a record identifier, retrieve a value for the named column in row identified by the recordID

Parameters

databaseFile	path to database file
recordID	identifies row within the file
fieldName	specifies a column

Returns: PMString value for the field specified, or empty if none exists with matching criteria

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetAssetDescriptionFromAssetIdentifier	(	const IWorkspace *	ws,
		const PMString &	uniqueAssetKey
	)		const

pure virtual

Determine the asset description given its unique identifier

Parameters

uniqueAssetKey

Returns: PMString

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetAssetDescriptionFromURI ( const URI & uri ) const

pure virtual

Determine the asset description given its URI

Parameters

uri

Returns: PMString

Implemented in CusDtLnkFacade.

virtual uint64 ICusDtLnkFacade::GetAssetSizeFromAssetIdentifier	(	const IWorkspace *	ws,
		const PMString &	uniqueAssetKey
	)		const

pure virtual

Determine size of asset given its unique identifier

Parameters

uniqueAssetKey

Returns: uint64 representing asset size

Implemented in CusDtLnkFacade.

virtual uint64 ICusDtLnkFacade::GetAssetTimestampFromAssetIdentifier	(	const IWorkspace *	ws,
		const PMString &	uniqueAssetKey
	)		const

pure virtual

Determine the timestamp (includes date) of last modification for asset given its unique identifier

Parameters

uniqueAssetKey

Returns: uint64 encoding the date/time asset was last modified

See Also: GlobalTime

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetCurrentlyChosenUniqueAssetKey ( const IWorkspace * ws ) const

pure virtual

Used only by the UI. Might consider refactoring out.

Returns: PMString

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetFieldValueFromAssetIdentifier	(	const IWorkspace *	ws,
		const PMString &	uniqueAssetKey,
		const PMString &	fieldName
	)		const

pure virtual

Given a unique key, retrieve named field from associated record

Parameters

uniqueAssetKey
fieldName

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetFirstPartOfPath ( const PMString & p ) const

pure virtual

Given a path, return the first part up to a directory separator (like forward or reverse slash or colon) ; so given something like xyz/abc, return xyz

Parameters

p	path of interest

Returns: PMString representing first component of path

Implemented in CusDtLnkFacade.

virtual IDFile ICusDtLnkFacade::GetLocalFileFromAssetIdentifier	(	const IWorkspace *	ws,
		const PMString &	uniqueAssetKey
	)		const

pure virtual

Determine the path in local filesystem to a "local replica" of asset given the unique identifier. Although we have no checkin/checkout protocol, we treat the path to the local replica as just another parameter from the database, rather than as a defining property of the link.

Parameters

uniqueAssetKey

Returns: IDFile

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::GetNthAssetDataBase	(	const IWorkspace *	ws,
		int32	index
	)		const

pure virtual

Accessor for the nth database name

Parameters

index

Returns: PMString

Implemented in CusDtLnkFacade.

PMString ICusDtLnkFacade::GetRecordFieldValueFromURI	(	const URI &	uri,
		PMString &	whichField
	)		const

Given a uri, retrieve named field from associated field key

Parameters

uri	the uri that reprents a record in some database (CSV) file.
whichField	the field key defined in CusDtLnkID.h

Returns: PMString field value in string

virtual PMString ICusDtLnkFacade::GetValueFromKey	(	const IWorkspace *	ws,
		const PMString &	key,
		const PMIID &	iid
	)		const

pure virtual

Retrieve an option stored in the session workspace (kWorkspaceBoss).

Parameters

key	key to use when looking up the option (stored in a map)
iid	identifies the interface (on workspace) where we should look

Returns: PMString representing the value of the option given the key, empty if not found

See Also: kWorkspaceBoss and adds that we have defined in this plug-in; ICusDtLnkOptions responsible for storing the key-value pairs persistently

Implemented in CusDtLnkFacade.

virtual bool16 ICusDtLnkFacade::HasOurAdornment ( const UIDRef & pageItemUIDRef ) const

pure virtual

Determine if the given layout object already has our page item adornment to signify it has a custom datalinked dependent

Parameters

pageItemUIDRef identifies layout object of interest

Returns: bool16 kTrue if it has the adornment, kFalse otherwise

Implemented in CusDtLnkFacade.

virtual UIDRef ICusDtLnkFacade::ImportImageAndLoadPlaceGun	(	const UIDRef &	docUIDRef,
		const PMString &	path,
		const PMString &	uniqueKey
	)

pure virtual

Given a document and a path in local file system to image, load the placegun, initializing a custom datalink with the uniqueKey supplied

Parameters

docUIDRef	which document to target
path	refers to asset in local filesystem
uniqueKey	unique identifier for custom datalink to create pointing at asset

Returns: UIDRef representing contents of the place gun

Implemented in CusDtLnkFacade.

virtual UIDRef ICusDtLnkFacade::ImportImageAndLoadPlaceGun	(	const UIDRef &	docUIDRef,
		const URI &	uri
	)

pure virtual

Given a document and an URI to image, load the placegun.

Parameters

docUIDRef	which document to target
uri	refers to asset uri

Returns: UIDRef representing contents of the place gun

Implemented in CusDtLnkFacade.

virtual ErrorCode ICusDtLnkFacade::InitializeDataLink	(	const IWorkspace *	ws,
		IDataLink *	dl,
		const IDFile &	file,
		const PMString &	formatName,
		const PMString &	uniqueAssetKey
	)

pure virtual

Initializes one of our custom datalinks so that it will behave correctly. Means that we don't have to use IDataLinkHelper::InitializeDataLink, which doesn't initialize our custom type in the way that is required.

Parameters

dl	datalink of interest, which should be one of our custom types
file	path to local replica of asset, if it exists
formatName	name of asset's format if known
uniqueAssetKey	unique key identifying asset in database

Returns: ErrorCode kSuccess if we succeeded, other ErrorCode otherwise

Precondition: IsOurCustomDataLink(dl) == true

Implemented in CusDtLnkFacade.

virtual bool16 ICusDtLnkFacade::IsOurCustomDataLink ( const ClassID & classID ) const

pure virtual

Determine if given ClassID is a custom datalink of our own type. In practice, we are looking to see if the class exposes an interface IBoolData with PMIID of IID_ICUSDTLNKDATALINKBOOLDATA. The rationale behind this was to allow multiple subclasses of our base type (kCusDtLnkBasicCustDataLinkBoss) to be identified through a marker interface, without explicitly examining ClassID.

Parameters

classID the ClassID of a datalink of interest

Returns: bool16 kTrue if this is one of our custom datalink boss classes, kFalse otherwise

Implemented in CusDtLnkFacade.

virtual bool16 ICusDtLnkFacade::IsOurCustomDataLink ( const UIDRef & linkUIDRef ) const

pure virtual

Determine if given UIDRef of an ILink is an our own type. In practice, we are looking to see if the link resource associated with the ILink has an URL whose schema is of ours.

Parameters

linkUIDRef the link of interest

Returns: bool16 kTrue if this is one of our link resource type, kFalse otherwise

Implemented in CusDtLnkFacade.

virtual bool16 ICusDtLnkFacade::NeedsOurAdornment ( const UIDRef & pageItemUIDRef ) const

pure virtual

Determine if the given layout object should have our page item adornment to signify it it has custom datalinked dependent

Parameters

pageItemUIDRef identifies layout object of interest

Returns: bool16 kTrue if it should have the adornment, kFalse otherwise

Implemented in CusDtLnkFacade.

virtual ErrorCode ICusDtLnkFacade::RemoveAdornment ( const UIDList & itemList )

pure virtual

Remove the page item adornment from list of layout objects

Parameters

itemList specifies layout objects to remove our adornment from

Returns: ErrorCode kSuccess if we succeeded, another ErrorCode otherwise

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::RetrieveUniqueKey ( IDataLink * dataLink ) const

pure virtual

Given a datalink, find the unique key associated with the asset it points to. For instance, this would be something like "alias-database-1.csv/1000141". This will only work for one of our own custom datalinks, with a normal datalink would just return an empty string.

Parameters

dataLink specifies the datalink object of interest

Returns: PMString containing its unique key, identifying the asset by combination of database name and record identifier.

Implemented in CusDtLnkFacade.

virtual ErrorCode ICusDtLnkFacade::SetCurrentlyChosenUniqueAssetKey	(	const IWorkspace *	ws,
		const PMString &	newKey
	)

pure virtual

Used only by the UI. Might consider refactoring out.

Parameters

newKey

Returns: ErrorCode

Implemented in CusDtLnkFacade.

virtual ErrorCode ICusDtLnkFacade::SetKeyValuePair	(	const IWorkspace *	ws,
		const PMString &	key,
		const PMString &	val,
		const PMIID &	iid
	)

pure virtual

Sets a persistent option on the session workspace (kWorkspaceBoss). These are stored in interface(s) of type ICusDtLnkOptions, differentiated by PMIID. These are:

IID_ICUSDTLNKOPTIONS for any options
IID_ICUSDTLNKDATABASESASOPTIONS for the list of databases only

Parameters

key	unique key to use when retrieving option
val	value to store
iid	identifies interface to use when storing value

Returns: ErrorCode kSuccess on success, other ErrorCode otherwise

See Also: ICusDtLnkOptions; kWorkspaceBoss

Implemented in CusDtLnkFacade.

virtual void ICusDtLnkFacade::StoreUniqueKey	(	IDataLink *	dataLink,
		const PMString &	uniqueAssetKey
	)

pure virtual

Given a custom datalink, associate it with a unique key to identify an asset that it refers to.

Parameters

dataLink
uniqueAssetKey

Implemented in CusDtLnkFacade.

virtual PMString ICusDtLnkFacade::TruncatePath	(	const PMString &	fullPath,
		bool16	useAnySeparator = `kTrue`,
		const PlatformChar &	useThisOne = `kTextChar_Solidus`
	)		const

pure virtual

Given a path of some kind, return the original with the last part of the path removed

Parameters

fullPath	input path to process
useAnySeparator	if any path separator can be used
useThisOne	if !useAnySeparator, which path separator to use

Returns: PMString with the input minus the last component

Implemented in CusDtLnkFacade.

virtual bool ICusDtLnkFacade::UniqueKeyToURI	(	const PMString &	uk,
		URI &	uri
	)		const

pure virtual

See Convert an unique key to URI, this is mainly for phase 2 conversion: when we get an old kCusDtLnkAliasedDataLinkBoss during conversion, we will query its IDataLink and use it to get the unique key used in CS3 and earlier, then we need to convert this unique key into an URI, which is used to create the new link resource under the new CS4 link architecture

Parameters

uk	the unique key that represent an asset for our custom data link, it has the format of "alias-database-1.csv/1000141"
uri	the URI for the link resource, it has the format of CusDtLnk://database_fulloath?recordID

Returns: True if the conversion succeeds, else false.

Implemented in CusDtLnkFacade.

virtual bool ICusDtLnkFacade::URIToIDFile	(	const URI &	uri,
		IDFile &	file
	)		const

pure virtual

Converts an URI that represents our CSV based asset to an IDFile.

Parameters

uri	[IN] URI to convert.
file	[OUT] Resulting IDFile.

Returns: True if the conversion succeeds, else false.

Implemented in CusDtLnkFacade.

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation