#include <IAMLockable.h>

Inheritance diagram for IAMLockable:

Public Types
enum	{ kDefaultIID = IID_IAMLOCKABLE }

enum	LockState { enUndefined = 0, enUnavailable, enAvailable, enLocked, enCheckedOut }

Public Member Functions
virtual bool16	IsLocked ()=0

virtual bool16	HasLock (UID objectUID=kInvalidUID)=0

virtual IAMLockable::LockState	GetLockState (UID objectUID=kInvalidUID)=0

virtual UID	GetLockObjectUID ()=0

virtual void	GetLockStatusStrings (std::map< int32, PMString > &stringTable)=0

virtual bool16	Lock (UIFlags uiFlags=kFullUI, bool16 allowOverride=kFalse, const PMString *userName=nil, UID objectUID=kInvalidUID)=0

virtual bool16	Relock (UIFlags uiFlags=kFullUI, bool16 allowOverride=kFalse, UID objectUID=kInvalidUID)=0

virtual bool16	Unlock (UIFlags uiFlags=kFullUI, bool16 allowOverride=kFalse, UID objectUID=kInvalidUID)=0

virtual IAMLockable::LockState	VerifyState (UIFlags uiFlags=kFullUI, UID objectUID=kInvalidUID)=0

virtual bool16	IsLocked (const PMString &userName)=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

The IAMLockable interface represents the lock for an asset. Implementations are responsible for determining the correct lock state and for interacting with the underlying asset management system to change the lock state as needed.

Member Enumeration Documentation

enum IAMLockable::LockState

Possible IAMLockable lock states for an asset. These states are mutually exclusive.
Enumerator
enUnavailable
Default before object initialization or if locking is not supported.
enAvailable
Cannot be locked at this time; e.g., new asset not yet saved.
enLocked
Can be locked (currently unlocked).
enCheckedOut
Asset is locked other than here. Locked here (note that all other instances of IAMLockable will report enLocked).

Member Function Documentation

virtual UID IAMLockable::GetLockObjectUID ( )

pure virtual

Retrieves the UID of the model object associated with the lock.

Returns: UID of a model object, or kInvalidUID.

virtual IAMLockable::LockState IAMLockable::GetLockState ( UID objectUID = kInvalidUID )

pure virtual

Retrieves the cached LockState. To get the latest LockState, call IAMLockable::VerifyState().

Parameters

objectUID is the UID of the model object associated with the lock.

Returns: cached LockState (not guaranteed to be current unless this method is called immediately after calling IAMLockable::VerifyState(). If the implementation of this interface supports locking at the individual page item level, then this method returns the IAMLockable::enCheckedOut state only if the lock is held for the specified objectUID.

virtual void IAMLockable::GetLockStatusStrings ( std::map< int32, PMString > & stringTable )

pure virtual

Retrieves the cached lock status data as PMStrings. To get the latest status, call IAMLockable::VerifyState before calling this method.

Parameters

stringTable

to be populated by the lock status <key/value> pairs. A <key/value> pair consists of the IManagedStatus::WGStatusType and the corresponding PMString value. If possible, implementations for story locks should provide at least the following status data:

IManagedStatus::enCheckedOutBy

IManagedStatus::enCheckedOutApp

IManagedStatus::enCheckedOutDoc

Omitting status data is not considered an error; however, UI alerts and status messages may be incomplete. Similarly, callers of this interface may safely ignore any unneeded data that an implementation provides.

See Also: IManagedStatus.

virtual bool16 IAMLockable::HasLock ( UID objectUID = kInvalidUID )

pure virtual

Tests if the asset has the lock (is locked here).

Parameters

objectUID is the UID of the model object associated with the lock.

Returns: kTrue if the LockState is enCheckedOut; kFalse otherwise.

virtual bool16 IAMLockable::IsLocked ( )

pure virtual

Tests if the asset is locked anywhere. Call VerifyState (see below) before calling this method.

Returns: kTrue if the LockState is either enLocked or enCheckedOut; kFalse otherwise.

virtual bool16 IAMLockable::IsLocked ( const PMString & userName )

pure virtual

Tests if a specified user name has the lock.

Parameters

userName is the test user name.

Returns: kTrue if locked for userName; kFalse otherwise.

virtual bool16 IAMLockable::Lock	(	UIFlags	uiFlags = `kFullUI`,
		bool16	allowOverride = `kFalse`,
		const PMString *	userName = `nil`,
		UID	objectUID = `kInvalidUID`
	)

pure virtual

Sets the lock by changing the LockState from enAvailable to enCheckedOut (or enLocked if userName that is passed in that is not equal to currentUser). This method fails if the current LockState is not enAvailable.

Parameters

uiFlags	standard flags for specifying permissible UI in performing this method.
allowOverride	when kTrue, allows changing of lock state even if the state is not currently IAMLockable::enAvailable.
userName	the user owning the lock file. If nil then the currentUser will be used.
objectUID	is the UID of the model object associated with the lock.

Returns: kTrue if the lock was successful; kFalse otherwise.

virtual bool16 IAMLockable::Relock	(	UIFlags	uiFlags = `kFullUI`,
		bool16	allowOverride = `kFalse`,
		UID	objectUID = `kInvalidUID`
	)

pure virtual

Relocks the lock for the same lock owner by updating any lock data as necessary. Note that this method will not override a lock; to override, use IAMLockable::Lock() instead.

Parameters

uiFlags	standard flags for specifying permissible UI in performing this method.
allowOverride	allow relock of asset not owned by current user. May not be supported by all implementations of IAMLockable.
objectUID	is the UID of the model object to be associated with the lock, for those implementations of this interface that support locking at the individual page item level.

Returns: kFalse if the relock operation failed or if the current lock state is not enCheckedOut. Implementations that do not require updating lock data should return kTrue.

virtual bool16 IAMLockable::Unlock	(	UIFlags	uiFlags = `kFullUI`,
		bool16	allowOverride = `kFalse`,
		UID	objectUID = `kInvalidUID`
	)

pure virtual

Unlocks the lock by changing the LockState from enCheckedOut to enAvailable.

Parameters

uiFlags	standard flags for specifying whether to show ui related to this operation or not
allowOverride	allow unlock of asset not owned by current user. May not be supported by all implementations of IAMLockable.
objectUID	is the UID of the model object associated with the lock.

Returns: kTrue if the unlock was successful; kFalse otherwise.

virtual IAMLockable::LockState IAMLockable::VerifyState	(	UIFlags	uiFlags = `kFullUI`,
		UID	objectUID = `kInvalidUID`
	)

pure virtual

Retrieves the actual (current) LockState by checking the lock token (or underlying asset management system). Depending on the implementation, calling this method could result in a significant time delay. Avoid calling this method during routine UI refreshes.

Parameters

uiFlags	controls UI that may be displayed in determining the LockState. For example, progress notification (if necessary) may be displayed for kFullUI, by not for kSuppressUI.
objectUID	is the UID of the model object associated with the lock.

Returns: the current LockState.

Enumerator
enUnavailable	Default before object initialization or if locking is not supported.
enAvailable	Cannot be locked at this time; e.g., new asset not yet saved.
enLocked	Can be locked (currently unlocked).
enCheckedOut	Asset is locked other than here. Locked here (note that all other instances of IAMLockable will report enLocked).

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation