The PhotoJazz engine never directly accesses PhotoJazz files. Whenever it needs to read from or write to a PhotoJazz file, it calls functions that you define. PhotoJazz uses an object-oriented C structure, JzStream, for this purpose, which contains a suite of callback functions for reading and writing, as well as a private data field reserved for your use. Each of the callback functions takes the JzStream object as its first argument.

Because PhotoJazz never accesses the PhotoJazz file directly, and only accesses it through your sequential-access mRead and mWrite callback functions, the PhotoJazz "file" doesn't have to be a proper file, but could be some other kind of stream, such as an area of memory, a segment of a larger file, or a network socket.

JzStream

The JzStream structure, which you create, contains a pointer to a callback function (mRead) to read a chunk of data, a pointer to a callback function (mWrite) to write a chunk of data, and a private data field (mData) for your sole use.

typedef struct JzStream {

JzStreamResult (*mRead)(JzStream *aStream, unsigned long aSize, void *aBuffer);
JzStreamResult (*mWrite)(JzStream *aStream, unsigned long aSize, const void *aBuffer);
unsigned long mData;

} JzStream;

You must create an instance of this structure, define an mRead function and an mWrite function, set the function pointers in the structure instance to your functions, and pass a pointer to the structure instance in to PhotoJazz each time you start to read or write a PhotoJazz file with JzReadBegin or JzWriteBegin. PhotoJazz stores this address and reads and writes by calling through the function pointers in the structure pointed to by that address.

JzStreamResult

typedef enum JzStreamResult {

kJzStreamResultOkay, //no error
kJzStreamResultOutOfMemory, //not enough heap memory
kJzStreamResultInvalidFileID, //bad OS-specific file number
kJzStreamResultNotOpen, //file not open for i/o
kJzStreamResultOutsideFile, //past end of file (or before start)
kJzStreamResultUnreadable, //no read access, not mounted, ...
kJzStreamResultUnwritable, //no write access, not mounted, ...
kJzStreamResultIOError, //bad media
kJzStreamResultAborted, //media ejected, process killed, ...
kJzStreamResultNotJazz, //not a PhotoJazz file
kJzStreamResultCorrupted, //bad check bits or bad CRC
kJzStreamResultInvalidSerialNumber, //bad user key or product key
kJzStreamResultCancelled, //user cancelled process
kJzStreamResultUnimplemented, //get a new version of PhotoJazz
kJzStreamResultInternalError, //bug
kJzStreamResultNotPersonalized, //no user key
kJzStreamResultMissingArgument, //NULL address
kJzStreamResultIncompleteArgument, //NULL structure member
kJzStreamResultInconsistentArgument, //value inconsistent with state
kJzStreamResultPrivateUnimplemented, //update your product
kJzStreamResultOutOfStackSpace, //not enough automatic memory
kJzStreamResultIgnored //reserved for internal use only

} JzStreamResult;

Your mRead and mWrite functions 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 JzStreamResult. The result returned by your mRead and mWrite functions is passed all the way through to be returned by the current JzRead or JzWrite function in progress.

mRead

The mRead callback function, which you define, takes as arguments a pointer to a JzStream structure (aStream), a byte count (aSize), and the address (aBuffer) of an input buffer; tries to read the specified number of bytes from the stream starting at the current stream position into the specified buffer; and adjusts the current stream position accordingly. When PhotoJazz calls this function, it passes back the address of the JzStream structure you gave it at the beginning of the file with JzReadBegin. If the read succeeds, your mRead function must return kJzStreamResultOkay (0). If the read fails, your mRead function should map the error code returned by the operating system into a JzStreamResult, and return that result code. To permit PhotoJazz to clean up its state properly, you must return control to PhotoJazz, which will then return your error result through the high-level JzRead function in progress.

JzStreamResult (*mRead)(JzStream *aStream, unsigned long aSize, void *aBuffer);

For example, a basic stdio implementation of mRead might be:

#include <stdio.h>
JzStreamResult JzStreamStdioRead(JzStream *aStream, unsigned long aSize, void *aBuffer){

FILE *lFile = (FILE*)aStream->mData;
JzStreamResult lResult = kJzStreamResultOkay;
long lSizeRead = fread(aBuffer, 1, aSize, lFile);
if (lSizeRead!=aSize){

lResult = kJzStreamResultIOError;

}
return lResult;

}

mWrite

JzStreamResult (*mWrite)(JzStream *aStream, unsigned long aSize, const void *aBuffer);

For example, a basic stdio implementation of mWrite might be:

#include <stdio.h>
JzStreamResult JzStreamStdioWrite(JzStream *aStream, unsigned long aSize, const void *aBuffer){

FILE* lFile = (FILE*)aStream->mData;
JzStreamResult lResult = kJzStreamResultOkay;
long lSizeWritten = fwrite(aBuffer, 1, aSize, lFile);
if (lSizeWritten!=aSize){

lResult = kJzStreamResultIOError;

}
return lResult;

}

mData

unsigned long mData;

Examples The PhotoJazz SDK comes with two sample implementations of JzStream: JzStreamStdio.{c,h} and JzStreamMacintosh.{c,h}.

A sample code snippet using JzStreamStdio might be:

#include "JzStreamStdio.h"
JzStream lStream;
lStream.mRead = JzStreamStdioRead;
lStream.mWrite = JzStreamStdioWrite;
lStream.mData = (unsigned long)fopen("myImage.jzz", "rw");

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