IConversionProvider Class Reference

#include <IConversionProvider.h>

Inheritance diagram for IConversionProvider:

Public Types
enum	ConversionStatus { kNothingToConvert, kMustConvert, kMustRemove, kCantConvert }
enum	IterationStatus { kFirstIteration, kMiddleIteration, kLastIteration }

Public Member Functions
virtual int32	CountConversions () const =0
virtual void	GetNthConversion (int32 i, VersionID *fromVersion, VersionID *toVersion) const =0
virtual int32	CountRemovedPlugins (const VersionID &fromVersion, const VersionID &toVersion) const =0
virtual PluginID	GetNthRemovedPlugin (const VersionID &fromVersion, const VersionID &toVersion, int32 n) const =0
virtual int32	CountIgnoredPlugins (const VersionID &fromVersion, const VersionID &toVersion) const =0
virtual PluginID	GetNthIgnoredPlugin (const VersionID &fromVersion, const VersionID &toVersion, int32 n) const =0
virtual int32	CountClassAliases () const =0
virtual int32	CountImplementationAliases () const =0
virtual void	GetNthClassAlias (int32 n, ClassID &fromID, VersionID &fromVersion, ClassID &toID, VersionID &toVersion) const =0
virtual void	GetNthImplementationAlias (int32 n, ImplementationID &fromID, VersionID &fromVersion, ImplementationID &toID, VersionID &toVersion) const =0
virtual int32	CountPlugins () const =0
virtual PluginID	GetNthPlugin (int32 n) const =0
virtual bool16	DoesConversionRenumberClass (int32 conversionIndex) const =0
virtual bool16	DoesConversionRenumberImplementation (int32 conversionIndex) const =0
virtual ConversionStatus	ShouldConvertImplementation (ImplementationID tag, ClassID context, int32 conversionIndex) const =0
virtual ConversionStatus	ShouldConvertClass (ClassID clsID, ImplementationID context, int32 conversionIndex) const =0
virtual ImplementationID	ConvertTag (ImplementationID tag, ClassID forClass, int32 conversionIndex, int32 inLength, IPMStream *inStream, IPMStream *outStream, IterationStatus whichIteration)=0
virtual ClassID	ConvertClass (ClassID clsID, ImplementationID embeddedContext, int32 conversionIndex, int32 inLength, IPMStream *inStream, IPMStream *outStream, IterationStatus whichIteration)=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

IConversionProvider is a key interface in the binary database conversion process. Although it is public, you are unlikely to need to call it directly. If you are writing a "code converter", you must implement this interface. However, it recommended that you base your converter on the CConversionProvider base class instead.

See Also

CConversionProvider

Member Enumeration Documentation

enum IConversionProvider::ConversionStatus

This enum is used to tell the Conversion Manager what the conversion provider would do to a specific class or implementation

Enumerator
kNothingToConvert	Conversion is not necessary
kMustConvert	Conversion is necessary: content will be modified
kMustRemove	Conversion is necessary: content will be removed
kCantConvert	Conversion is not possible

enum IConversionProvider::IterationStatus

Any conversion could require multiple calls to the converter: for instance, converting from 1->3 could turn into two calls, 1->2 and 2->3. It is important that if there is any embedded data (data that will require a callback into the ConversionMgr to convert) that it be converted only once for any given conversion. The IterationStatus flag tells the conversion provider what place in the overall conversion process it is being called in.

Enumerator
kFirstIteration	First of multiple
kMiddleIteration	Any middle conversion of multiple
kLastIteration	Last or only conversion

Member Function Documentation

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

pure 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

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

virtual int32 IConversionProvider::CountClassAliases ( ) const

pure virtual

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

Returns

The count

Implemented in CConversionProvider.

virtual int32 IConversionProvider::CountConversions ( ) const

pure virtual

Return the number of conversions this converter can convert.

Returns

The count

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

virtual int32 IConversionProvider::CountImplementationAliases ( ) const

pure virtual

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

Returns

The count

Implemented in CConversionProvider.

virtual int32 IConversionProvider::CountPlugins ( ) const

pure virtual

Return the number of plugins that this converter represents.

Returns

The count

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

virtual bool16 IConversionProvider::DoesConversionRenumberClass ( int32  conversionIndex ) const

pure 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

Implemented in CConversionProvider.

virtual bool16 IConversionProvider::DoesConversionRenumberImplementation ( int32  conversionIndex ) const

pure 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

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

virtual void IConversionProvider::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

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

virtual PluginID IConversionProvider::GetNthPlugin ( int32  n ) const

pure virtual

Return the Nth plugin.

Parameters

n	IN Which plugin

Returns

The plugin ID, or kInvalidPlugin if n is invalid

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.

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

pure 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

Implemented in CConversionProvider.