The PhotoJazz file format is extensible, and supports private product-specific data classes. See the discussion under JzWritePrivateChunk.

When the BitJazz library encounters a private chunk while reading a PhotoJazz file, it calls an interpret function that you define. PhotoJazz uses an object-oriented C structure, JzInterpreter, for this purpose, which contains a callback function for interpreting, as well as a private data field reserved for your use. The callback function takes the JzInterpreter object as its first argument.

JzInterpreter

typedef struct JzInterpreter {

JzInterpreterResult (*mInterpret)(struct JzInterpreter *aInterpreter, unsigned long aOwner, unsigned long aClass, JzFlags aFlags, unsigned long aSize, void *aData);
unsigned long mData;

} JzInterpreter;

You must create an instance of this structure, define an mInterpret function, set the function pointer in the structure instance to your function, and pass a pointer to the structure instance in to PhotoJazz each time you start to read a PhotoJazz file with JzReadBegin. PhotoJazz stores this address and interprets private chunks by calling through the function pointers in the structure pointed to by that address.

mInterpret

When PhotoJazz calls this function, it passes back the address of the JzInterpreter structure you gave it at the beginning of the file with JzReadBegin. If your interpreter recognizes the chunk Class, it processes the chunk data however it needs to, and returns the result kJzInterpreterResultMyChunk. If your software does not recognize the chunk, your mInterpret function must return kJzInterpreterResultUnknownChunk. If you encounter an operating-system error (such as running out of memory) while processing the chunk, you must return control to PhotoJazz so that it can clean up properly.

JzInterpreterResult (*mInterpret)(struct JzInterpreter *aInterpreter, unsigned long aOwner, unsigned long aClass, JzFlags aFlags, unsigned long aSize, void *aData);

Your mInterpret function returns a JzInterpreterResult. The following JzInterpreterResult values are currently defined:

typedef enum JzInterpreterResult {

kJzInterpreterResultMyChunk, //okay, recognized chunk
kJzInterpreterResultUnknownChunk, //okay, unrecognized chunk
kJzInterpreterResultOutOfMemory, //not enough memory
kJzInterpreterResultUnimplemented, //update your product
kJzInterpreterResultCount

} JzInterpreterResult;

Your mInterpret function should map operating-system-specific result codes to these result codes. If necessary, you can also return a negative error result (such as an OSErr on the Macintosh), by casting it to a JzInterpreterResult. The result returned by your mInterpret function is passed all the way through to be returned by the current JzRead function in progress. If your JzInterpreterResult is one of these standard values, it is mapped to a JzStreamResult as follows: The result kJzInterpreterResultMyChunk is mapped to kJzStreamResultOkay. If your JzInterpreter returns kJzInterpreterResultUnknownChunk for a critical chunk, the result is mapped to kJzStreamResultUnimplemented; for an ancillary chunk, the result is mapped to kJzStreamResultOkay. The result kJzInterpreterResultOutOfMemory is mapped to kJzStreamResultOutOfMemory, as expected. And kJzInterpreterResultUnimplemented is mapped to kJzStreamResultPrivateUnimplemented.

If your product defines no private chunks and does not recognize those of any other products, you can use this basic "ignorant" interpreter:

static JzInterpreterResult MyInterpret(JzInterpreter */*aInterpreter*/, unsigned long /*aOwner*/, unsigned long /*aClass*/, JzFlags /*aFlags*/, unsigned long /*aSize*/, void */*aData*/){

return kJzInterpreterResultUnknownChunk;

}

If you do write private chunks to your PhotoJazz files, a skeleton of your interpreter might look something like this:

static JzInterpreterResult MyInterpret(JzInterpreter */*aInterpreter*/, unsigned long aOwner, unsigned long aClass, JzFlags /*aFlags*/, unsigned long aSize, void *aData){

if (aOwner!=kJzOwnerYou){

return kJzInterpreterResultUnknownChunk;

} else switch (aClass){

case kYourClass0:{

Process your Class-0 chunk!
break;

} case kYourClass1:{

Process your Class-1 chunk!
break;

} default:{

return kJzInterpreterResultUnimplemented;
break;

}

}
return kJzInterpreterResultMyChunk;

}

mData

The mData member of the JzInterpreter structure is solely for your use; PhotoJazz never accesses it. Depending on your interpreter's needs, you can ignore it, put an identifying number in it, or put in a pointer to a structure containing additional information. PhotoJazz accesses the JzInterpreter structure by reference only and defines no hidden members of its own in the structure, so you are free to define your own structure with a JzInterpreter as its first member instead of forcing your ancillary data to fit in the mData field.

Examples

A sample code snippet using one of the MyInterpret functions defined above might be:

JzInterpreter lInterpreter;
lInterpreter.mInterpret = MyInterpret;

Depending on your needs, you may prefer to create a global, static, or dynamic JzInterpreter instead of a local one.