InDesign SDK  20.5
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
IAMServiceProvider Class Referenceabstract

#include <IAMServiceProvider.h>

Inheritance diagram for IAMServiceProvider:
IPMUnknown

Classes

class  AssetHints
 

Public Types

enum  { kDefaultIID = IID_IAMSERVICEPROVIDER }
 
enum  AssetService {
  enInvalidService = 0, enEnsureLatestVersion = kWorkgroupPrefix + 1, enCheckIn = kWorkgroupPrefix + 2, enRevert = kWorkgroupPrefix + 3,
  enCheckOut = kWorkgroupPrefix + 4, enCancelCheckOut = kWorkgroupPrefix + 5, enTerminate = kWorkgroupPrefix + 6, enInitialize = kWorkgroupPrefix + 7,
  enAfterSave = kWorkgroupPrefix + 8, enAfterSaveAs = kWorkgroupPrefix + 9, enUpdateStoredAssetReference = kWorkgroupPrefix + 10, enUpdateProxyVersionNumber = kWorkgroupPrefix + 11,
  enInvalidateProxyVersionNumber = kWorkgroupPrefix + 12, enGetUniqueAssetLocation = kWorkgroupPrefix + 13, enBatchCheckIn = kWorkgroupPrefix + 14, enAfterCheckIn = kWorkgroupPrefix + 15,
  enBeforeCheckOut = kWorkgroupPrefix + 16, enAfterCancelCheckOut = kWorkgroupPrefix + 17, enUpdateLinkLocation = kWorkgroupPrefix + 18, enRelink = kWorkgroupPrefix + 19,
  enUnembed = kWorkgroupPrefix + 20, enStoreCheckInData = kWorkgroupPrefix + 21, enRetrieveCheckInData = kWorkgroupPrefix + 22
}
 

Public Member Functions

virtual bool16 CanService (const IDFile &file, const IAMServiceProvider::AssetHints *hints=nil)=0
 
virtual bool16 CanService (const IManageableAsset *asset)=0
 
virtual bool16 CanUpdateScriptedAssetData (UIDRef assetRef, const PMString &scriptString, int32 scriptID)=0
 
virtual bool16 GetLinkResourceId (const IDFile &inFile, ILinkResource::ResourceId &outResourceId)=0
 
virtual IAMServiceGetService (int32 assetServiceID)=0
 
virtual ErrorCode Init ()=0
 
virtual bool16 IsTemporaryVersion (const IDFile &file)=0
 
virtual bool16 IsVersioned (const IDFile &file)=0
 
virtual IOpenFileCmdData::OpenFlags OverrideOpenFlags (const IDFile &file, IOpenFileCmdData::OpenFlags inOpenFlags)=0
 
virtual ErrorCode UpdateScriptedAssetData (UIDRef assetRef, const PMString &scriptString, int32 scriptID)=0
 
virtual bool16 IsWriteable (const IDFile &assetFile)=0
 
virtual bool16 GetLockData (const IDFile &assetFile, IManagedStatus::StatusStringTable &outLockData, UIFlags uiFlags=kFullUI)=0
 
- Public Member Functions inherited from IPMUnknown
virtual IPMUnknownQueryInterface (PMIID interfaceID) const =0
 
virtual void AddRef () const =0
 
virtual void Release () const =0
 

Detailed Description

The IAMServiceProvider interface provides IAMService instances and other asset management services.

See Also
IAMService.

Member Enumeration Documentation

The AssetService enum defines the service ID numbers for all of the asset management services currently used by the InDesign/InCopy/InDesignServer codebase. This list may be extended as needed by defining new unique service ID numbers.
Enumerator
enInvalidService 

This is the default AssetService ID.

enEnsureLatestVersion 

This service ensures that the local (cached) file for an asset is the latest version by downloading the file from the asset store in cases where the cached file is missing or a newer version is available. If the cached file has been modified, the download should not be done without user authorization even if a newer version of the asset is available; i.e., local changes are never clobbered automatically.

Provided that a local copy of the asset exists, implementations of this service should report kSuccess for this service even if the asset management system reports a download error. This policy assures that the existing local copy of the asset at least can be opened so that status alerts can be displayed with more infomation.

Input IAMServiceData parameters:

IAMService Data Identifier        | Data Type     | Notes

--------------------------------—+------------—+-----------------------------------— IAMService::enTargetAsset | IDFile | When specified, the service should use | | the IDFile rather than the IManageableAsset * | | argument on the IAMService::Do() method.

Output IAMServiceData parameters: None.

See Also
IAMService.
IAMServiceData.
enCheckIn 

Checks an asset into the asset management system and unlocks it. For most implementations this service will copy local changes to a secure location, such as the asset management database. After this service completes successfully, the asset is available for check out (see the enCheckOut service).

Input IAMServiceData parameters:

IAMService Data Identifier       | Data Type          | Notes

-------------------------------—+-----------------—+-----------------------------------— IAMService::enTargetAsset | IDFile | When specified, the service should use | | the IDFile rather than the IManageableAsset * | | argument on the IAMService::Do() method. IAMService::enCheckInComment | PMString | Empty PMString signifies a blank comment. IAMService::enForceSave | IWorkgroupFacade:: | Controls overwriting latest version with | ForceSave | local changes. IAMService::enContentSaver | void * | Pointer to ISaveAssetContent callback. | | When nil, save is not needed. IAMService::enOverrideAuthority | boolean flag | For assignment packaging feature. IAMService::enCheckOutToUserName | PMString | For assignment packaging feature. IAMService::enUIFlags | UIFlags | UI permitted for use by the service.

Output IAMServiceData parameters: None.

See Also
ISaveAssetContent.
IWorkgroupFacade.
enRevert 

Reverts local changes to an asset.

    Input IAMServiceData parameters: None.

    Output IAMServiceData parameters: None.
enCheckOut 

Checks out an asset for editing. If locking is supported, the asset is also locked to indicate to others that it is in use.

Input IAMServiceData parameters:

IAMService Data Identifier       | Data Type | Notes

-------------------------------—+--------—+-----------------------------------— IAMService::enCheckOutToUserName | PMString | Empty PMString signifies a blank comment. IAMService::enUIFlags | UIFlags | UI permitted for use by the service.

Output IAMServiceData parameters: None.

enCancelCheckOut 

Cancels a previous checkout without reverting the asset's contents. This service fails if the asset has been edited.

Input IAMServiceData parameters:

IAMService Data Identifier       | Data Type | Notes

-------------------------------—+--------—+-----------------------------------— IAMService::enUIFlags | UIFlags | UI permitted for use by the service.

Output IAMServiceData parameters: None.

enTerminate 

Executes any termination code required before an IManageableAsset instance is destroyed.

    Input IAMServiceData parameters: None.

    Output IAMServiceData parameters: None.     
enInitialize 

Executes any initialization code to make an IManageableAsset instance ready for use.

    Input IAMServiceData parameters:



        IAMService Data Identifier  | Data Type    | Notes

       -----------------------------+--------------+--------------------------------------

        IAMService::enUseStoredData | boolean flag | If set, init using asset management data

                                                   | stored with the link. This parameter applies

                                                   | only to managed linked assets.



    Output IAMServiceData parameters: None.         
enAfterSave 

Executes any followup code required by the asset management system at the conclusion of a document Save operation. For example, as part of its asset status bookkeeping, Version Cue requires notification after a document has been saved locally.

Input IAMServiceData parameters: None. Output IAMServiceData parameters: None.

enAfterSaveAs 

Executes any followup code required by the asset management system at the conclusion of a document SaveAs operation.

Input IAMServiceData parameters: None. Output IAMServiceData parameters: None.

enUpdateStoredAssetReference 

Updates stored asset reference data for a managed link. The stored data (if any) depends on the requirements of the asset management system. For example, an opaque data byte sequence supplied by the Version Cue API is stored with the IDataLink when the link references a Version Cue asset.

Input IAMServiceData parameters: None. Output IAMServiceData parameters: None.

enUpdateProxyVersionNumber 

Upates the proxy version number for a managed link. The proxy version number is the version number of the asset used to create the proxy stored in an InDesign document. For example, the proxy may be the low-res version of a placed image, or the latest text in a placed InCopy story. The proxy version number is used to determine when the proxy itself (not the link) is out of date.

Input IAMServiceData parameters: None. Output IAMServiceData parameters: None.

enInvalidateProxyVersionNumber 

Invalidates the proxy version number for a managed link.

    Input IAMServiceData parameters: None.

    Output IAMServiceData parameters: None.         
enGetUniqueAssetLocation 

Provides a unique location with respect to the asset management system. This service is useful for providing a default location when saving a new asset.

Input IAMServiceData parameters:

IAMService Data Identifier        | Data Type     | Notes

--------------------------------—+------------—+-----------------------------------— IAMService::enTargetAsset | IDFile | Proposed location.

Output IAMServiceData parameters:

IAMService Data Identifier        | Data Type     | Notes

--------------------------------—+------------—+-----------------------------------— IAMService::enUniqueAssetLocation | IDFile | Location provided by asset management sytem.

enBatchCheckIn 

Checks in a list of assets. This service is useful when it is faster for an asset management system to check in multiple assets in batch rather than one at a time.

Input IAMServiceData parameters:

IAMService Data Identifier          | Data Type                  |  Notes

----------------------------------—+-------------------------—+---------------------------------— IAMService::enTargetAsset(implicit) | IAMServiceData::IDFileList | IDFiles to checkin. IAMService::enCheckInComment | PMString | Empty PMString signifies a blank comment.

Output IAMServiceData parameters: None.

enAfterCheckIn 

Performs any follow-up actions needed after an enCheckIn service completes.

    Input IAMServiceData parameters: None.

    Output IAMServiceData parameters: None.     
enBeforeCheckOut 

Performs any actions needed before an enCheckIn service is executed.

    Input IAMServiceData parameters: None.

    Output IAMServiceData parameters: None.     
enAfterCancelCheckOut 

Performs any follow-up actions needed after an enCancelCheckout service completes.

    Input IAMServiceData parameters: None.

    Output IAMServiceData parameters: None.     
enUpdateLinkLocation 

The service updates the IDataLink for a link to a managed asset. The service is useful for updating links to assets that have been moved or renamed.

Input IAMServiceData parameters: None. Output IAMServiceData parameters: None.

enRelink 

This service relinks a story page item. Used for porting from IInCopyBridgeCmdSuite::Relink.

    Input IAMServiceData parameters: None.

    Output IAMServiceData parameters: None.     
enUnembed 

This service unembeds story content to an external asset location. Used for porting from IInCopyBridgeCmdSuite::Relink.

Input IAMServiceData parameters:

IAMService Data Identifier       | Data Type             | Notes

-------------------------------—+--------------------—+-----------------------------------— IAMService::enCommandUndoability | ICommand::Undoability | Applies to any ICommands executed by the service IAMService::enUIFlags | UIFlags | UI permitted for use by the service.

Output IAMServiceData parameters: None.

enStoreCheckInData 

This service stores checkin data for later retrieval. Useful for situations in which it is impractical to pass checkin data parameters explicitly throughout the APIs.

Input IAMServiceData parameters: IAMService::enTargetAsset IDFile & IAMService::enCheckInComment PMString Output IAMServiceData parameters: None.

enRetrieveCheckInData 

This service retrieves checkin data that was previously stored.

    Input IAMServiceData parameters: IAMService::enTargetAsset IDFile.

    Output IAMServiceData parameters: IAMService::enCheckInComment PMString.        

Member Function Documentation

virtual bool16 IAMServiceProvider::CanService (const IDFilefile,
const IAMServiceProvider::AssetHintshints = nil 
)
pure virtual

This form of the CanService method tests if the service provider can service (owns) a specified file; i.e., if the file can be handled by the asset management system. If the asset management system does not support files, this method should always return kFalse (the second form of this method can be used to determine ownership).

Parameters
fileis the IDFile to test for ownership.
hintscontain more information about the file (input parameter).
Returns
kTrue if the service provider recognizes the file; kFalse otherwise.
virtual bool16 IAMServiceProvider::CanService (const IManageableAssetasset)
pure virtual

This for of the CanService method tests if the service provider can service an IManageableAsset instance.

Parameters
assetis a valid pointer to an IManageableAsset interface.
Returns
kTrue if the service provider recognizes the IManageableAsset; kFalse otherwise.
virtual bool16 IAMServiceProvider::CanUpdateScriptedAssetData (UIDRef assetRef,
const PMStringscriptString,
int32 scriptID 
)
pure virtual

The CanUpdateScriptedAssetData method tests if the asset management service provider recognizes the specified script data for the purpose of updating it as necessary. This method is used in conjunction with the IAMServiceProvider::UpdateScriptedAssetData method.

Parameters
assetRefis the UIDRef of a boss that aggregates the IManageableAsset (IID_IMANAGEABLEASSET) interface.
scriptStringis the IScriptRequestData converted to a PMString.
scriptIDis the script data item's ScriptID.
Returns
kTrue if the service provider recognizes the script data; kFalse otherwise.
virtual bool16 IAMServiceProvider::GetLinkResourceId (const IDFileinFile,
ILinkResource::ResourceIdoutResourceId 
)
pure virtual

Retrieves the ILinkResource::ResourceId for a specified file.

Parameters
inFilea resource IDFile.
outResourceIdis set to the ResourceId if available.
Returns
kTrue if outResourceId was set; kFalse otherwise.
virtual bool16 IAMServiceProvider::GetLockData (const IDFileassetFile,
IManagedStatus::StatusStringTable & outLockData,
UIFlags uiFlags = kFullUI 
)
pure virtual

This method retrieves available lock data associated with a locked file-based asset.

Parameters
assetFilerepresents an existing file-based asset.
outLockDatais populated with the relevant IManagedStatus::WGStatusType data strings.
uiFlagscontrols UI that may be displayed in determining the lock data.
Returns
kTrue if the asset is locked and data is available; kFalse otherwise.
See Also
IManagedStatus.
virtual IAMService* IAMServiceProvider::GetService (int32 assetServiceID)
pure virtual

The GetService method obtains an instance of an IAMService interface for a specified AssetService id. The IAMService pointer is returned with a refcount of 1; the caller of this method is responsible for releasing the IAMService pointer. Suggested usage:

InterfacePtr<IAMService> pService( myAMServiceProvider->GetService( myServiceID ) );

The advantage of the suggested usage is that the IAMService pointer will be released automatically when pService goes out of scope.

This method is typically implemented as a switch statement as in the following example.

Implementation example:

IAMService* InCopyAMServiceProvider::GetService( int32 assetServiceID )

{

    IAMService * service(nil);

    switch ( assetServiceID )

    {

        case IAMServiceProvider::enInitialize : 

            service = ::CreateObject2<IAMService>( kICInitializeStoryServiceBoss );                 

            break;          

        case IAMServiceProvider::enCheckOut :

            service = (IAMService*)::CreateObject( kICCheckOutServiceBoss, IID_IAMSERVICE );

            break;

        case IAMServiceProvider::enCancelCheckOut :

        case IAMServiceProvider::enRevert :

            service = (IAMService*)::CreateObject( kICCancelCheckOutServiceBoss, IID_IAMSERVICE );

            break;

        case IAMServiceProvider::enCheckIn :

            service = (IAMService*)::CreateObject( kICCheckInServiceBoss, IID_IAMSERVICE );

            break;                  

    }   

    return service;

} // end InCopyAMServiceProvider::GetService()      

Parameters
assetServiceIDa 32-bit service identifier supported by the IAMServiceProvider implementation. This need not be a predefined IAMServiceProvider::AssetService identifier as long as it is unique.
Returns
a valid IAMService pointer if an implementation exists, othersize returns nil.
virtual ErrorCode IAMServiceProvider::Init ()
pure virtual

The Init method prepares the asset management service provider for use. This method may be called any number of times, but it must be called at least once before calling any other method on the service provider.

Returns
kSuccess if initialization succeeded or if already successfully initialized; kFalse if the service provider is unavailable.
virtual bool16 IAMServiceProvider::IsTemporaryVersion (const IDFilefile)
pure virtual

This method tests if a file is a temporary file created by the asset management system from an older version of an asset. The tempory file is typically used for viewing past versions. Note that this was originally a Version Cue concept, but have relevance to other asset management systems.

Parameters
fileis an IDFile containing a path to an existing temporary file.
Returns
kTrue if the file is a temporary file of an older version of an asset; kFalse otherwise.
virtual bool16 IAMServiceProvider::IsVersioned (const IDFilefile)
pure virtual

This method tests if an asset is versioned; that is, it tests if there are historical versions of an asset.

Parameters
fileis an IDFile containing a valid file path.
Returns
kTrue if the IDFile represents a versioned asset; kFalse otherwise.
virtual bool16 IAMServiceProvider::IsWriteable (const IDFileassetFile)
pure virtual

The IsWriteable method tests if it is currently safe to write to an asset file. Since writeability is transient, this method should be called immediately before writing. This method is useful when an IAMLockable interface is unavailable for determining writeability, as when determining if a text frame can be exported as a story asset over an existing story file.

Parameters
assetFilehas a valid path.
Returns
kTrue if the assetFile can be legally overwritten or if the assetFile does not yet exist. Caution should be used in returning kTrue, especially for LiveEdit assets, since a file may not be overwritten while it is in use by another app or story text frame. It is up to the implementaton of this method to honor the LiveEdit workflow. The default return value should be kFalse.
See Also
IAMLockable.
virtual IOpenFileCmdData::OpenFlags IAMServiceProvider::OverrideOpenFlags (const IDFilefile,
IOpenFileCmdData::OpenFlags inOpenFlags 
)
pure virtual

The OverrideOpenFlags method allows the asset management service provider to override the file open flags for an InDesign document asset.

Parameters
fileis an IDFile containing a path to an existing InDesign document file.
inOpenFlagsare the default IOpenFileCmdData::OpenFlags.
Returns
the inOpenFlags unless the file must be opened in a different way. For example, a temporary version file (see IsTemporaryVersion() method) should be opened with the IOpenFileCmdData::kOpenCopy flag.
virtual ErrorCode IAMServiceProvider::UpdateScriptedAssetData (UIDRef assetRef,
const PMStringscriptString,
int32 scriptID 
)
pure virtual

The UpdateScriptedAssetData method modifies asset data from a scripting environment.

Parameters
assetRefis the UIDRef of a boss that aggregates the IManageableAsset (IID_IMANAGEABLEASSET) interface.
scriptStringis the IScriptRequestData converted to a PMString.
scriptIDis the script data item's ScriptID.
Returns
kSuccess if the update succeeds; otherwise returns a failure error code.