KCMS CMM Developer's Guide

Chapter 6 `KcsProfileFormat` Derivative

In This Chapter

This chapter discusses the following to help you create a KcsProfileFormat class derivative that is dynamically loadable at runtime:

External entry points with an example
Member function override rules
Helpful information on attributes, transformations, loading and what you need to consider with a protected KcsProfileFormat derivative

Figure 6-1 shows the relationship of the KcsProfileFormat class to the parent classes in the KCMS class hierarchy. See Figure 1-2 for an illustration of all the relevant KCMS classes.

Figure 6-1 `KcsProfileFormat` Derivative

External Entry Points

The KCMS framework uses external entry-points to load your derivative as an executable. The mandatory and optional entry points are described.

Mandatory

When you derive from a KcsProfileFormat class, the mandatory external entry points are:

extern

long KcsDLOpenPfmtCount; KcsProfileFormat *KcsCreatePfmt(KcsStatus *sStat,

KcsIO *aIO); KcsProfileFormat *KcsCreatePfmtBlnk(KcsStatus *aStat,  	KcsId

aCmmId, KcsVersion aCmmVersion, KcsId aProfId,  	KcsVersion

aProfVersion);

KcsCreatePfmt()() creates an instance of a KcsProfileFormat derivative. The derivative is determined by the version information contained within the data represented by aIO. This corresponds to the KcsLoadProfile()() call.

KcsCreatePfmtBlnk()() creates an instance of a KcsProfileFormat derivative that is determined by aProfId. This creates a blank profile version instance with no objects associated with the returned instance. It initializes the CMM type identifier, the CMM version, and the profile version from aCmmId, aCmmVersion, and aProfVersion, respectively.

Optional

When you derive from a KcsProfileFormat class, the optional "C" based entry points are:

KcsStatus

KcsInitPfmt(); KcsStatus

KcsCleanupPfmt();

Examples

The following example shows you how to use the entry points when creating a KcsProfileFormat derivative.

Example 6-1 `KcsProfileFormat` Class Entry Points Example

extern long

KcsDLOpenPfmtCount = 0;  /* Global initialization - constructor can be used */

KcsStatus KcsInitPfmt(long libMajor, long libMinor, long *myMajor, long

*myMinor) { 	// Set up the return values 	*myMajor = KCS_MAJOR_VERSION;

	*myMinor = KCS_MINOR_VERSION;  	//Check the major version 	if (libMajor !=

KCS_MAJOR_VERSION) 		return (KCS_CMM_MAJOR_VERSION_MISMATCH);  	//Currently,

if minor version of library is less than the KCMS  	// minor version, return

an error. 	if (libMinor != KCS_MINOR_VERSION) 		return

(KCS_CMM_MINOR_VERSION_MISMATCH);  	//Library guarantees if your minor version

number is greater than 	//KCMS minor version number, it will handle it. No

more init. 	return(KCS_SUCCESS); }  /* Clean up global initialization */

KcsStatus KcsCleanupPfmt() { 	KcsStatus sStat; 	return(KCS_SUCCESS); }  /*

Create a profile format derivative based on information passed in,  * there is

profile data associated with it. Corresponds to the  * KcsCreateProfile() API

call. */ KcsProfileFormat * KcsCreatePfmtBlnk(KcsStatus *aStat, KcsId aCmmId, 

	KcsVersion aCmmVersion, KcsId aProfId, KcsVersion aProfileVersion) {

	//Create the new derivative 	return(new KcsProfileFormatInterColor3_0(aStat,

aCmmId,  		aCmmVersion, aProfId, aProfileVersion)); }  /* Create a profile

format derivative using the supplied IO.  * Corresponds to the

KcsLoadProfile() API call. */ KcsProfileFormat * KcsCreatePfmt(KcsStatus

*aStat, KcsIO *aIO) { 	//Create the new derivative 	return(new

KcsProfileFormatInterColor3_0(aStat, aIO));

}

Member Function Override Rules

The following table tells you which KcsProfileFormat member functions you must override and can override when deriving from this class. The member functions indicated with an "X" in the Must column are requiredto successfully derive from this base class. All of these member functions are defined in the kcspfmt.h header file and the KCMS CMM Reference Manual.

Table 6-1 KcsProfileFormat Member Function Override Rules


Member Function	Override Rules
Member Function	Must	Can
`deleteXform()()`		X
`dirtyAttrCache()()`		X
`dirtyXformCache()()`		X
`generateLoadWhat()()`		X
`generateXformAttributes()()`		X
`getObject()()`		X
`getObject()()`		X
`getSaveSize()()`		X
`initEmptyFormat()()`		X
`isSupported()()`		X
`KcsProfileFormat()()`	X
`~KcsProfileFormat()()`		X
`load()()`		X
`loadObjectMap()()`		X
`postAttrCompose()()`		X
`save()()`		X
`saveNew()()`		X
`saveObjectMap()()`		X
`setCmmId()()`		X
`setObject()()`		X
`unload()()`		X
`unloadWhenMatch()()`		X

Attributes

All attributes of a profile are in the KcsAttributeSet object returned from the getObject()() method. (Note that KcsProfileFormat includes two public getObject()() methods. The method discussed here gets the KcsAttributeSet: the other, discussed in "Transformations " " below, returns a KcsXform.) This attribute instance includes public attributes from all of the formats, regardless of where they reside in the data store. The returned attributes' object of this class contains all of the attributes that describe this profile--including all attributes in the public sections of the various profile formats as well as any private attributes.

Do not confuse these attributes with those associated with individual transformations. Attributes associated with individual transformations are stored in the profile's data store but are not added to the attributes object returned from the getObject()() method of this class. Since this class uses the KcsChunkSet object, it can separate out these attributes from the transformation attributes. The KcsProfile base class informs the KcsXforms it loads about any attributes needed to construct themselves.

Transformations

As many transformation slots exist as there are valid operations for a profile. Use the getObject(KcsXformType)() overloaded method to retrieve the correct KcsXform*. (KcsProfileFormat includes two public getObject()() methods. Use the one that returns the specified KcsXform.)

Like attributes, it does not matter whether the KcsXform wanted is in a public header or in a private part of the profile. This class abstracts out the placement and type. A profile format with a mixture of public and private parts for transformation representation is supported.

Loading

Like most loadable derivatives, use the load()() method to force a specific load state. It takes the hints supplied and loads the instance based on those hints. The KcsProfileFormat class loads those objects and any supporting data returned from the getObject() methods.

If a request is made that requires the loading of unloaded state, the instance goes to static store and loads what is required to accomplish the request. It is up to you whether the objects loaded stay loaded between getObject()() calls.

You can cache any object returned from the getObject()() methods. This means that the load()() and save()() methods must be propagated to the cached object. Since this class keeps its own cache of objects and it is expected to be optimized, let KcsProfileFormat handle all caching and call getObject()() before that particular object is needed.

Error Protocols

The load()() method can take a loadhint with multiple bits set. The following error protocols are used:

If the only error the derivative receives during load is KCS_PFMT_NO_DATA_SUPPORT_4_REQUEST and everything loads successfully, return KCS_SUCCESS.

Say, for example, you ask for a forward complete and the derivative also tries to load the reverse complete (for optimization). If the reverse receives an error but forward succeeds, KCS_SUCCESS is returned.

If nothing requested is available, return KCS_PFMT_NO_DATA_SUPPORT_4_REQUEST.

Any other errors that occur should be returned, and the object should unload itself before exiting. A failure during load()() (other than KCS_PFMT_NO_DATA_SUPPORT_4_REQUEST) results in an object for which the loadhints requested are unloaded.

Protected Derivatives

Differences in physical profile formats is hidden by abstracting the physical pieces of all profile parts into a standard set of objects that represent them. This can be a problem when a new profile format contains a new part that cannot be represented by any of the objects. It is neither a transformation nor an attribute.

If the new derivation can support the existing objects, you can use a new derivation with getObject()(). If you need a new object type, see if the derivation supports the new object. Any new profile format that supports this new object is derived from that new format derivative instead of the base class.

If you use the KcsChunkSet class appropriately in your new derivative, implemention is minimal. The base class allows the minimum derivative to only override the save()() method by having the derivative assign chunks with hard-coded offsets for the pieces of a profile during save()(). Then load()() automatically loads the pieces from the hard-coded offsets by using the chunk set mechanism. If, however, your derivative's pieces are split into smaller pieces, you must override load()() to gather the smaller pieces into the original objects.

Base Class Support

The base class supports the caching objects and transformation map saving. It contains the KcsXform * array, an KcsAttribute * and supports the getObject()() and setObject()() overloads. Most derivative profile formats implement these virtuals: initEmptyFormat()(), isSupported()(), load()(), and save()().

A derivative can define and use the base class data elements protected during load()(), and the base class passes them to you.

Retrievable Objects

To find out if a part of an instance is supported, the derivative needs to support the pure virtual method isSupported(KcsLoadHint). This method returns KCS_SUCCESS for only its loadable parts and, if the request is not supported. It takes a loadhint that indicates what can be returned from all getObject()() overloads; this includes whether the forward xform is supported as well as any new parts.

An unsupported object is represented by a NULL in one of the object pointers (attributes or xforms) and it returns KCS_PFMT_NO_DATA_SUPPORT_4_REQUEST.

Chapter 6 KcsProfileFormat Derivative