test

KCMS CMM Reference Manual

Chapter 3 KcsChunkSet Class

This chapter describes the KCMS framework KcsChunkSet class. You can manage blocks (or chunks) of data arranged in tagged file format with Chunk classes. The ICC profile format is directly analogous to the KcsChunkSet. The KcsChunkSet class is derived from the KcsShareable class. See Chapter 1, KcsShareable Class for a description of the KcsShareable class.

As you read this chapter, you will find it helpful to have access to the following header files:

Note -

It is highly recommended that you do not use any of the variables and functions for handle-based memory in the these header files. Handle-based memory is not required on the Solaris system.

The header file for the class is kcschunk.h. The constant and #define identifiers for this class are defined in the kcsids.h header file as:

const KcsId KcsSharChkSId = {(0x43686B53UL)}; /* 'ChkS' */
#define KcsSharChkSIdd (0x43686B53UL) /* 'ChkS' */

In addition to the KcsShareable methods overridden by this class, there are methods for managing chunks of data. The protected and public members are described.

Protected Members

The KcsChunkSet class has the following protected members.

Table 3-1 KcsChunkSet Protected Members

Protected Member 

Description 

 
virtual KcsStatus
readChunkBuffer(const KcsChunkId aChunkId,
 	void *aChunk,unsigned long *aSizeRead,
 	unsigned long aSizeWanted = 0);

Reads a chunk of bytes indicated by a chunk Id. 

KCS_CHUNK_ID_ERR is returned if no chunk Ids match in the profile. Assumes the aChunk buffer is allocated. Get the buffer size with getChunkSize() which is defined in Table 3-2.

 
virtual KcsStatus
writeChunkBuffer(const KcsChunkId aChunkId,
 	void *aChunk, const unsigned long aSize,
 	KcsCompressBoolean aCompress = KcsCompress,
 	KcsLocationEnum aLocationEnum =
 		KcsLocationUnspecified,
 	long aOffset = KcsNoOffsetSpecified);

Writes a chunk of bytes to a new chunk in the profile, given a void *. Returns a new chunk Id. If a particular location or offset is specified, other chunks are moved to write this chunk at the specified location.

Public Members

The KcsChunkSet class has the following public members.

Table 3-2 KcsChunkSet Public Members

Public Member 

Description 

 
virtual KcsStatus
createChunkId(KcsChunkId *aNewChunkId,
 	unsigned long aChunkSize = 0,
 	KcsLocationEnum aLocationEnum =
 		aKcsLocationUnspecified,
 	long aChunkOffset = KcsNoOffsetSpecified,
	KcsRegisterBoolean aRegister =
 		KcsIgnoreIdSpecified);

Allocates aNewChunkId for a chunk introduced to the data type. Puts a new entry into the chunk map. The size of the chunk can be specified, or by default equals 0. The chunk location can be specified in aLocationEnum and aChunkOffset or defaults can be used. Creates specific chunk ids with aRegister.

 
virtual KcsStatus
deleteChunk(const long aChunkId);

Deletes the chunk (and its chunk map entry) identified by a chunkId. You are required to check whether any other objects are using this chunk.

 
virtual unsigned long
getChunkSetLength(KcsStatus *aStatus);

Returns the length of the domain of the chunk set. 

 
virtual long
getChunkSetOffset(KcsStatus *aStatus);

Returns the offset of the beginning of the domain of the chunk set. 

 
virtual unsigned long
 getChunkSize(KcsStatus *aStatus,
 	KcsChunkId aChunkId);

Returns the chunk size identified by aChunkId. If the chunk is compressed, returns the uncompressed chunk size.

 
virtual KcsIO *
getIO();

Returns the chunk set's I/O object. 

 
virtual KcsChunkId
 getTopChunkId(KcsStatus *aStatus,
 	unsigned long aSize = 0,
 	long aOffset = KcsNoOffsetSpecified);

Returns the chunk Id of the top chunk which stores information about other chunks. Read this chunk first because it tells what is contained in the other chunks. Or you can specify the size of the chunk and the chunk's offset; by default, aSize = 0 and aOffset = KcsNoOffsetSpecified. If no top chunk exists , call createChunkId().

 
virtual Boolean
isEqual(KcsChunkSet *aNotherCS);

Checks if this chunk set is the same as another chunk set. 

 
KcsChunkSet(KcsStatus *aStatus);

Constructor without an I/O object. 

 
KcsChunkSet(KcsStatus *aStatus,
 	KcsIO *aIoObj,
 	unsigned long aChunkSetLength = KcsUseEOF,
 	KcsSaveBoolean aSaveMapping =
 		KcsSaveChunkSet,
 	int Format = 0);

Constructor of a chunk set instance based on an I/O object.  

aChunkSetLength can be set to the length of the static store managed by the chunk set if not equal to the length managed by the I/O object. Otherwise, by default, aChunkSetLength is set to the end of the static store managed by the I/O object.

When a particular file format does not allow writing out the chunk map, aSaveMapping is False; otherwise, aSaveMapping is, by default, True indicating that the chunk containing the chunk map should be saved. 

~KcsChunkSet();

Destructor. 

 
KcsStatus 
readChunk(const KcsChunkId aChunkId, void *aChunk,
 	unsigned long *aSizeRead,
 	unsigned long aSizeWanted = 0);

Reads a chunk set. 

 
virtual KcsStatus
setChunkSetOffset(long aOffset);

Sets aOffset to the beginning of the domain of the chunk set.

 
virtual KcsStatus
setChunkSetPrivateOffset(const long aOffset)

Sets the chunk set's private offset.  

 
virtual KcsStatus
setIO(KcsIO *aIoObj);

Sets the chunk set's I/O object. 

 
virtual unsigned long
updateChunkUseCount(KcsStatus *aStatus,
    KcsChunkId aChunkId, long aDelta, 
    unsigned long aComparisonCount);

Calls the ChunkMap object to change the use count of a particular chunk. Compares the use count with an expected value, aComparisonCount.

 
KcsStatus
writeChunk(KcsChunkId aChunkId,
    void *aChunk,
    const unsigned long aSize,
 	KcsCompressBoolean aCompress = KcsCompress,
 	KcsLocationEnum aLocationEnum =
 		KcsLocationUnspecified,
 	long aOffset = KcsNoOffsetSpecified);

Writes a chunk set.

Example

The following code shows you some examples of how to use these KcsChunkSet class member functions: getChunkSet(), getChunkSize(), readChunk(), and writeChunk().

Example 3-1 Getting, Reading and Writing a Chunk 

KcsChunkId				myChunkId;
 KcsStatus				aStat;
 KcsChunkSet*				chunkSet;
 char*				mftData;
 u_long				mftSize;
 u_long				mftWanted;

 // Get the chunk data
 chunkSet = getChunkSet();
 if (chunkSet == NULL)
 	return (KCS_INTERNAL_CLASS_CORRUPTED);

 //Get the size
 mftSize = chunkSet->getChunkSize(&aStat, myChunkId);
 if (aStat != KCS_SUCCESS)
 	return(aStat);

 //Make space for the data
 mftData = NULL;
 if ((mftData = malloc((u_int)mftSize)) == NULL) {
 	return (KCS_MEM_ALLOC_ERR);
 }

 //Read it
 aStat = chunkSet->readChunk(myChunkId, mftData, &mftWanted,
 				mftSize);
 if (aStat != KCS_SUCCESS)
 	return (aStat);

 //Zero it out and write it back
 memset(mftData, 0, mftSize);
 aStat = chunkSet->writeChunk(myChunkId, mftData, mftSize);
 if (aStat != KCS_SUCCESS)
 	return (aStat);