CConversionProvider Class Reference

#include <CConversionProvider.h>

Inheritance diagram for CConversionProvider:

Public Member Functions
	CConversionProvider (PluginID plugin, IPMUnknown *boss)
virtual int32	CountConversions () const =0
virtual void	GetNthConversion (int32 n, VersionID *fromVersion, VersionID *toVersion) const =0
virtual int32	CountRemovedPlugins (const VersionID &fromVersion, const VersionID &toVersion) const
virtual PluginID	GetNthRemovedPlugin (const VersionID &fromVersion, const VersionID &toVersion, int32 n) const
virtual int32	CountIgnoredPlugins (const VersionID &fromVersion, const VersionID &toVersion) const
virtual PluginID	GetNthIgnoredPlugin (const VersionID &fromVersion, const VersionID &toVersion, int32 n) const
virtual int32	CountClassAliases () const
virtual int32	CountImplementationAliases () const
virtual void	GetNthClassAlias (int32 n, ClassID &fromID, VersionID &fromVersion, ClassID &toID, VersionID &toVersion) const
virtual void	GetNthImplementationAlias (int32 n, ImplementationID &fromID, VersionID &fromVersion, ImplementationID &toID, VersionID &toVersion) const
virtual int32	CountPlugins () const
virtual PluginID	GetNthPlugin (int32 n) const
virtual bool16	DoesConversionRenumberClass (int32 conversionIndex) const
virtual bool16	DoesConversionRenumberImplementation (int32 conversionIndex) const
virtual IConversionProvider::ConversionStatus	ShouldConvertImplementation (ImplementationID tag, ClassID context, int32 conversionIndex) const
virtual IConversionProvider::ConversionStatus	ShouldConvertClass (ClassID clsID, ImplementationID context, int32 conversionIndex) const
virtual ImplementationID	ConvertTag (ImplementationID tag, ClassID forClass, int32 conversionIndex, int32 inLength, IPMStream *oldData, IPMStream *newData, IterationStatus whichIteration)
virtual ClassID	ConvertClass (ClassID clsID, ImplementationID embeddedContext, int32 conversionIndex, int32 inLength, IPMStream *oldData, IPMStream *newData, IterationStatus whichIteration)
Public Member Functions inherited from CPMUnknown< IConversionProvider >
IPMUnknown *	QueryInterface (PMIID interfaceID) const
void	AddRef () const
void	Release () const
void	PreDirty (ImplementationID prop=kInvalidImpl, bool16 allowModification=kTrue)
void	PreDirtyNoMessage (ImplementationID prop=kInvalidImpl, bool16 allowModification=kTrue)
	CPMUnknown (const CPMUnknown &)=delete
CPMUnknown &	operator= (const CPMUnknown &)=delete

Protected Member Functions
void	RemoveImplementation (ImplementationID implID, ClassID classID, int32 majorFormat, int32 minorFormat)
void	RemoveClass (ClassID classID, int32 majorFormat, int32 minorFormat)
void	RemovePlugin (PluginID plugin, int32 majorFormat, int32 minorFormat)
void	IgnorePlugin (PluginID plugin, int32 majorFormat, int32 minorFormat)
void	MoveClass (ClassID fromClass, PluginID fromPlugin, int32 fromMajorFormat, int32 fromMinorFormat, ClassID toClass, int32 toMajorFormat, int32 toMinorFormat)
void	MoveImplementation (ImplementationID fromImpl, PluginID fromPlugin, int32 fromMajorFormat, int32 fromMinorFormat, ImplementationID toImpl, int32 toMajorFormat, int32 toMinorFormat)
Protected Member Functions inherited from CPMUnknown< IConversionProvider >
	CPMUnknown (IPMUnknown *boss)

Additional Inherited Members
Public Types inherited from IConversionProvider
enum	ConversionStatus { kNothingToConvert, kMustConvert, kMustRemove, kCantConvert }
enum	IterationStatus { kFirstIteration, kMiddleIteration, kLastIteration }
Protected Attributes inherited from CPMUnknown< IConversionProvider >
HelperInterface	fHelperInterface

Detailed Description

This class provides a useful base implementation of IConversionProvider. It handles most of the details of the rather complex interaction between IConversionMgr and IConversionProvider. A fully functional conversion provider can be written by using the protected methods of this class to define the equivalent of Schema Directives and the overriding key IConversionProvider methods to perform data-based conversions.

The public methods in this class are uncommented because they are documented in IConversionProvider.

See Also

IConversionMgr

IConversionProvider

Member Function Documentation

virtual ClassID CConversionProvider::ConvertClass ( ClassID  clsID, ImplementationID  embeddedContext, int32  conversionIndex, int32  inLength, IPMStream *  inStream, IPMStream *  outStream, IterationStatus  whichIteration  )

virtual

Convert the contents of the class from the old format to the new. Returns the new ClassID, which will be the same as the clsID parameter, unless the class was renumbered.

If kInvalidClass is returned, the UID will be deleted from the database.

Parameters

clsID	IN The ID of the class to be converted
embeddedContext	IN The ID of the implementation that contains the class, or kInvalidImpl
conversionIndex	IN The index (in this conversion provider's list of possible conversions) to be performed
inLength	IN Byte length of the incoming data to be converted
inStream	IN Stream that contains the data to be converted
outStream	IN Stream that will contain the converted data
whichIteration	IN Which conversion is this in a series of conversion steps

Returns

The post-conversion ID of the class, or kInvalidClass if the class was removed

Implements IConversionProvider.

virtual ImplementationID CConversionProvider::ConvertTag ( ImplementationID  tag, ClassID  forClass, int32  conversionIndex, int32  inLength, IPMStream *  inStream, IPMStream *  outStream, IterationStatus  whichIteration  )

virtual

Convert the contents of the implementation from the old format to the new . The incoming contents from inStream will be whatever was written by the ReadWrite function in version inVersion. The outgoing contents into outStream should be whatever will be expected by ReadWrite for the output version. Returns the new ImplementationID, which will be the same as the tag parameter, unless the implementation was renumbered.

If ConvertTag doesn't write any data to the output stream, the ImplementationID and associated data are removed from the UID.

Parameters

tag	IN The ID of the implementation to be converted
forClass	IN The ID of the class that contains the implementation
conversionIndex	IN The index (in this conversion provider's list of possible conversions) to be performed
inLength	IN Byte length of the incoming data to be converted
inStream	IN Stream that contains the data to be converted
outStream	IN Stream that will contain the converted data
whichIteration	IN Which conversion is this in a series of conversion steps

Returns

The post-conversion ID of the implementation, or kInvalidImpl if the implementation was removed

Implements IConversionProvider.

virtual int32 CConversionProvider::CountClassAliases ( ) const

virtual

Return the number of "aliases" (Created when a Class is moved from one Plugin to another).

Returns

The count

Implements IConversionProvider.

virtual int32 CConversionProvider::CountConversions ( ) const

pure virtual

Return the number of conversions this converter can convert.

Returns

The count

Implements IConversionProvider.

virtual int32 CConversionProvider::CountIgnoredPlugins ( const VersionID &  fromVersion, const VersionID &  toVersion  ) const

virtual

Return the number of plugins set to "Ignore" between the specified range of format numbers.

Parameters

fromVersion	IN The source version
toVersion	IN The target version

Returns

The count

Implements IConversionProvider.

virtual int32 CConversionProvider::CountImplementationAliases ( ) const

virtual

Return the number of "aliases" (Created when an Implementation is moved from one Plugin to another).

Returns

The count

Implements IConversionProvider.

virtual int32 CConversionProvider::CountPlugins ( ) const

virtual

Return the number of plugins that this converter represents.

Returns

The count

Implements IConversionProvider.

virtual int32 CConversionProvider::CountRemovedPlugins ( const VersionID &  fromVersion, const VersionID &  toVersion  ) const

virtual

Return the number of plugins removed between the specified range of format numbers.

Parameters

fromVersion	IN The source version
toVersion	IN The target version

Returns

The count

Implements IConversionProvider.

virtual bool16 CConversionProvider::DoesConversionRenumberClass ( int32  conversionIndex ) const

virtual

Would this conversion renumber a class?

Parameters

conversionIndex

IN Which conversion (in this conversion provider's list)

Returns

kTrue if the conversion would renumber a class

Implements IConversionProvider.

virtual bool16 CConversionProvider::DoesConversionRenumberImplementation ( int32  conversionIndex ) const

virtual

Would this conversion renumber an implementation?

Parameters

conversionIndex

IN Which conversion (in this conversion provider's list)

Returns

kTrue if the conversion would renumber an implementation

Implements IConversionProvider.

virtual void CConversionProvider::GetNthClassAlias ( int32  n, ClassID &  fromID, VersionID &  fromVersion, ClassID &  toID, VersionID &  toVersion  ) const

virtual

Return the n'th class alias.

Parameters

n	IN Which alias
fromID	OUT The source class ID
fromVersion	OUT The source version
toID	OUT The target class ID
toVersion	OUT The target version

Implements IConversionProvider.

virtual void CConversionProvider::GetNthConversion ( int32  i, VersionID *  fromVersion, VersionID *  toVersion  ) const

pure virtual

Return the n'th conversion supported by this converter. The answer is in the form of a pair of VersionIDs. You might think of it as meaning "The i-th conversion transforms data in the format 'fromVersion' to format 'toVersion'"

Parameters

i	IN Which conversion
fromVersion	OUT The source version of this conversion
toVersion	OUT The target version of this conversion

Implements IConversionProvider.

virtual PluginID CConversionProvider::GetNthIgnoredPlugin ( const VersionID &  fromVersion, const VersionID &  toVersion, int32  n  ) const

virtual

Return the n'th ignored plugin.

Parameters

fromVersion	IN The source version
toVersion	IN The target version
n	IN Which plugin

Returns

The ignored plugin ID, or kInvalidPlugin if n is invalid

Implements IConversionProvider.

virtual void CConversionProvider::GetNthImplementationAlias ( int32  n, ImplementationID &  fromID, VersionID &  fromVersion, ImplementationID &  toID, VersionID &  toVersion  ) const

virtual

Return the n'th implementation alias.

Parameters

n	IN Which alias
fromID	OUT The source implementation ID
fromVersion	OUT The source version
toID	OUT The target implementation ID
toVersion	OUT The target version

Implements IConversionProvider.

virtual PluginID CConversionProvider::GetNthPlugin ( int32  n ) const

virtual

Return the Nth plugin.

Parameters

n	IN Which plugin

Returns

The plugin ID, or kInvalidPlugin if n is invalid

Implements IConversionProvider.

virtual PluginID CConversionProvider::GetNthRemovedPlugin ( const VersionID &  fromVersion, const VersionID &  toVersion, int32  n  ) const

virtual

Return the n'th removed plugin.

Parameters

fromVersion	IN The source version
toVersion	IN The target version
n	IN Which plugin

Returns

The removed plugin ID, or kInvalidPlugin if n is invalid

Implements IConversionProvider.

void CConversionProvider::IgnorePlugin ( PluginID  plugin, int32  majorFormat, int32  minorFormat  )

protected

For use by subclasses to tell us when a plugin's priority should be set to "Ignored".

Parameters

classID	IN Which plugin is being ignored
majorFormat	IN As of this major format number
minorFormat	IN and this minor format number

void CConversionProvider::MoveClass ( ClassID  fromClass, PluginID  fromPlugin, int32  fromMajorFormat, int32  fromMinorFormat, ClassID  toClass, int32  toMajorFormat, int32  toMinorFormat  )

protected

For use by subclasses to tell us when a class has moved from another plugin. It is implied that the class is moving to the plugin that contains this conversion provider.

Parameters

fromClass	IN Which class is being moved
fromPlugin	IN From which plugin
fromMajorFormat	IN The old plugin's major format number at the time of the move
fromMinorFormat	IN and its minor format number
toClass	IN The new class ID
toMajorFormat	IN This plugin's major format number at the time of the move
toMinorFormat	IN and its minor format number

void CConversionProvider::MoveImplementation ( ImplementationID  fromImpl, PluginID  fromPlugin, int32  fromMajorFormat, int32  fromMinorFormat, ImplementationID  toImpl, int32  toMajorFormat, int32  toMinorFormat  )

protected

For use by subclasses to tell us when an implementation has moved from another plugin. It is implied that the implementation is moving to the plugin that contains this conversion provider.

Parameters

fromImpl	IN Which implementation is being moved
fromPlugin	IN From which plugin
fromMajorFormat	IN The old plugin's major format number at the time of the move
fromMinorFormat	IN and its minor format number
toImpl	IN The new implementation ID
toMajorFormat	IN This plugin's major format number at the time of the move
toMinorFormat	IN and its minor format number

void CConversionProvider::RemoveClass ( ClassID  classID, int32  majorFormat, int32  minorFormat  )

inlineprotected

For use by subclasses to tell us when a class has been removed.

Parameters

classID	IN Which class is being removed
majorFormat	IN As of this major format number
minorFormat	IN and this minor format number

void CConversionProvider::RemoveImplementation ( ImplementationID  implID, ClassID  classID, int32  majorFormat, int32  minorFormat  )

protected

For use by subclasses to tell us when an implementation has been removed from a class.

Parameters

implID	IN Which implementation is being removed
classID	IN From which class
majorFormat	IN As of this major format number
minorFormat	IN and this minor format number

void CConversionProvider::RemovePlugin ( PluginID  plugin, int32  majorFormat, int32  minorFormat  )

protected

For use by subclasses to tell us when a plugin has been removed.

Parameters

classID	IN Which plugin is being removed
majorFormat	IN As of this major format number
minorFormat	IN and this minor format number

virtual IConversionProvider::ConversionStatus CConversionProvider::ShouldConvertClass ( ClassID  clsID, ImplementationID  context, int32  conversionIndex  ) const

virtual

Returns whether the class must be run through the converter to update from one version to another.

Parameters

clsID	IN Which class
context	IN In which context, kInvalidImpl means "in any context"
conversionIndex	IN Which conversion (in this conversion provider's list)

Returns

The conversion status

Implements IConversionProvider.

virtual IConversionProvider::ConversionStatus CConversionProvider::ShouldConvertImplementation ( ImplementationID  tag, ClassID  context, int32  conversionIndex  ) const

virtual

Returns whether the implementation must be run through the converter to update from one version to another.

Parameters

tag	IN Which implementation
context	IN In which context, kInvalidClass means "in any context"
conversionIndex	IN Which conversion (in this conversion provider's list)

Returns

The conversion status

Implements IConversionProvider.