StreamUtil Class Reference

#include <StreamUtil.h>

Static Public Member Functions
static IPMStream *	CreateDBStreamRead (IDataBase *db, UID id)
static IPMStream *	CreateDBStreamWrite (IDataBase *db, UID id)
static IPMStream *	CreateCloudDBStreamRead (IDataBase *db, UID uid)
static IPMStream *	CreateCloudDBStreamWrite (IDataBase *db, UID uid)
static IPMStream *	CreateCopyStream (IDataBase *src, IDataBase *dest, IXferBytes *xfer=nil)
static IPMStream *	CreateDBStreamCopy (IDataBase *src, IDataBase *dest, UID id, IPMUnknown *pmobject=nil)
static IPMStream *	CreateFileStreamRead (const IDFile &sysFile, uint32 mode=kOpenIn, OSType fileType=0x3f3f3f3f, OSType creator=0x3f3f3f3f)
static IPMStream *	CreateFileStreamWrite (const IDFile &sysFile, uint32 mode=kOpenOut, OSType fileType=0x3f3f3f3f, OSType creator=0x3f3f3f3f)
static IPMStream *	CreateFileStreamReadLazy (const IDFile &sysFile, uint32 mode=kOpenIn, OSType fileType=0x3f3f3f3f, OSType creator=0x3f3f3f3f)
static IPMStream *	CreateFileStreamWriteLazy (const IDFile &sysFile, uint32 mode=kOpenOut|kOpenTrunc, OSType fileType=0x3f3f3f3f, OSType creator=0x3f3f3f3f)
static IPMStream *	CreateObjectTextFileStreamWrite (IDataBase *db, const IDFile &sysFile, uint32 mode=kOpenOut, OSType fileType=0x3f3f3f3f, OSType creator=0x3f3f3f3f)
static IPMStream *	CreateResourceStreamRead (const RsrcSpec &spec, bool16 useLocaleIndexResource=kTrue)
static IPMStream *	CreateObjectResourceStreamRead (const RsrcSpec &spec, IDataBase *db)
static void	ResetStreamContentsChanged (IPMStream *)
static void	SetStreamContentsChanged (IPMStream *)
static bool16	StreamContentsChanged (IPMStream *)
static IPMStream *	CreateCustomDBStreamWrite (IDataBase *source, UID sourceUID, IDataBase *target, UID targetUID)
static IPMStream *	CreateDCXCompositeStream (ClassID clsID, const AdobeDCX::CompositePtr compositePtr)
Bauhaus managed streams
static IPMStream *	CreateManagedFileStreamRead (const IDFile &sysFile, uint32 mode=kOpenIn, OSType fileType=0x3f3f3f3f, OSType creator=0x3f3f3f3f)
static IPMStream *	CreateManagedFileStreamReadLazy (const IDFile &sysFile, uint32 mode=kOpenIn, OSType fileType=0x3f3f3f3f, OSType creator=0x3f3f3f3f)
Memory-based streams
static IPMStream *	CreatePointerStreamRead (char *buffer, size_t len)
static IPMStream *	CreatePointerStreamWrite (char *buffer, size_t len)
static IPMStream *	CreateMemoryStreamRead (IXferBytes *underlyingXferBytes, bool16 takeOwnership=kFalse, bool16 recycleBoss=kTrue)
static IPMStream *	CreateMemoryStreamWrite (IXferBytes *underlyingXferBytes, bool16 takeOwnership=kFalse, bool16 recycleBoss=kTrue)

Detailed Description

StreamUtil is a class of static functions that create and manipulate InDesign streams.

It is provided for convenience and ease of use.



Note that any of the create stream methods will return nil if there is an error 

creating a stream (e.g., file cannot be opened, etc.). So client code should check

for nil on return.



Example Code:

        InterfacePtr<IPMStream> s(StreamUtil::CreateFileStreamRead(myFile));

        if (s)  {

            // read from file

        }

        else {

            // handle error

Also, in all cases, the stream returned is a referenced object, and the caller is

responsible for releasing it. Typically this is handled via InterfacePtr, as in 

the example above.

Member Function Documentation

static IPMStream* StreamUtil::CreateCloudDBStreamRead ( IDataBase *  db, UID  uid  )

static

Create a Read stream from the cloud document to read the content from database.

Parameters

db	what database the object is in
UID	the object in the database to access

Returns

IPMStream* the new stream, or nil if the stream cannot be opened. For Internal USE only right now.

static IPMStream* StreamUtil::CreateCloudDBStreamWrite ( IDataBase *  db, UID  uid  )

static

Create a Read stream from the cloud document to read the content from database.

Parameters

db	what database the object is in
UID	the object in the database to access

Returns

IPMStream* the new stream, or nil if the stream cannot be opened. For Internal Use ONLY right now.

static IPMStream* StreamUtil::CreateCopyStream ( IDataBase *  src, IDataBase *  dest, IXferBytes *  xfer = nil  )

static

For internal use only. Open a stream for copying a database record.

Parameters

src	database to copy from
dest	database to copy to
IXerBytes*	the handler to use for the copy

Returns

IPMStream* the new stream, or nil if the stream cannot be opened.

static IPMStream* StreamUtil::CreateDBStreamCopy ( IDataBase *  src, IDataBase *  dest, UID  id, IPMUnknown *  pmobject = nil  )

static

For internal use only. Copy a uid from the src database into a new object in the destination database.

Parameters

src	database to copy from
dest	database to copy to
dest	object to copy to
pmobject	used in translating UIDs during the copy (for internal use only)

Returns

IPMStream* the new stream, or nil if the stream cannot be opened.

static IPMStream* StreamUtil::CreateDBStreamRead ( IDataBase *  db, UID  id  )

static

Open a stream for reading a database object

Parameters

db	what database the object is in
UID	the object in the database to access

Returns

IPMStream* the new stream, or nil if the stream cannot be opened.

static IPMStream* StreamUtil::CreateDBStreamWrite ( IDataBase *  db, UID  id  )

static

Open a stream for writing a database record.

Parameters

db	what database the object is in
UID	the object in the database to access

Returns

IPMStream* the new stream, or nil if the stream cannot be opened.

static IPMStream* StreamUtil::CreateFileStreamRead ( const IDFile &  sysFile, uint32  mode = kOpenIn, OSType  fileType = 0x3f3f3f3f, OSType  creator = 0x3f3f3f3f  )

static

Open a stream for reading from a file.

Parameters

sysFile	the file to read from
mode	mode for opening the file (open for read, read/write, etc.)
fileType	on Macintosh, this is the Finder file type
creator	on Macintosh, this the Finder creator type

Returns

IPMStream* the new stream, or nil if the file couldn't be opened.

static IPMStream* StreamUtil::CreateFileStreamReadLazy ( const IDFile &  sysFile, uint32  mode = kOpenIn, OSType  fileType = 0x3f3f3f3f, OSType  creator = 0x3f3f3f3f  )

static

Open a stream for reading from a file. The file is opened on demand, the first time a read is requested. Note that in this case, you may get back a valid stream from the CreateFileStreamReadLazy method, but the file hasn't yet been opened. It will be opened as the result of a subsequent read request. If the open fails, the stream will go into an error state

See Also

GetStreamState. Client code should check for this.

Parameters

sysFile	the file to read from
mode	mode for opening the file (open for read, read/write, etc.)
fileType	on Macintosh, this is the Finder file type
creator	on Macintosh, this the Finder creator type

Returns

IPMStream* the new stream, or nil if the file couldn't be opened.

static IPMStream* StreamUtil::CreateFileStreamWrite ( const IDFile &  sysFile, uint32  mode = kOpenOut, OSType  fileType = 0x3f3f3f3f, OSType  creator = 0x3f3f3f3f  )

static

Open a stream for writing to a file.

Parameters

sysFile	the file to read from
mode	mode for opening the file (open for read, read/write, etc.)
fileType	on Macintosh, this is the Finder file type
creator	on Macintosh, this the Finder creator type

Returns

IPMStream* the new stream, or nil if the file couldn't be opened.

static IPMStream* StreamUtil::CreateFileStreamWriteLazy ( const IDFile &  sysFile, uint32  mode = kOpenOut|kOpenTrunc, OSType  fileType = 0x3f3f3f3f, OSType  creator = 0x3f3f3f3f  )

static

Open a stream for writing to a file. The file is opened on demand, the first time a write is requested. Note that in this case, you may get back a valid stream from the CreateFileStreamWriteLazy method, but the file hasn't yet been opened. It will be opened as the result of a subsequent write request. If the open fails, the stream will go into an error state

See Also

GetStreamState. Client code should check for this.

Parameters

sysFile	the file to read from
mode	mode for opening the file (open for read, read/write, etc.)
fileType	on Macintosh, this is the Finder file type
creator	on Macintosh, this the Finder creator type

Returns

IPMStream* the new stream, or nil if the file couldn't be opened.

static IPMStream* StreamUtil::CreateManagedFileStreamRead ( const IDFile &  sysFile, uint32  mode = kOpenIn, OSType  fileType = 0x3f3f3f3f, OSType  creator = 0x3f3f3f3f  )

static

Open a stream for reading from a file, downloads the file if it's not already in local repository. Returns nil if file cannot be opened.

Parameters

sysFile	the file to read from
mode	mode for opening the file (open for read, read/write, etc.)
fileType	on Macintosh, this is the Finder file type
creator	on Macintosh, this the Finder creator type

Returns

IPMStream* the new stream, or nil if the file couldn't be opened.

static IPMStream* StreamUtil::CreateManagedFileStreamReadLazy ( const IDFile &  sysFile, uint32  mode = kOpenIn, OSType  fileType = 0x3f3f3f3f, OSType  creator = 0x3f3f3f3f  )

static

Open a stream for reading from a file. File is actually opened on demand, the first time a read is requested. Downloads the file if it's not already in local repository. Returns nil if file cannot be opened.

Parameters

sysFile	the file to read from
mode	mode for opening the file (open for read, read/write, etc.)
fileType	on Macintosh, this is the Finder file type
creator	on Macintosh, this the Finder creator type

Returns

IPMStream* the new stream, or nil if the file couldn't be opened.

static IPMStream* StreamUtil::CreateMemoryStreamRead ( IXferBytes *  underlyingXferBytes, bool16  takeOwnership = kFalse, bool16  recycleBoss = kTrue  )

static

Open a stream for reading from memory.

Parameters

underlyingXferBytes	IXferBytes instance the memory stream will read from.
takeOwnership	Denotes whether the stream is to be the sole owner of the given IXferBytes.
recycleBoss	Denotes whether to utilize a recycle boss for the stream.\ If the underlying IXferBytes must be released to free up resources, a file for instance, it is recommended to not use a recycle boss since the IXferBytes might not be released until the stream boss is reused.

Returns

IPMStream* the new read stream

static IPMStream* StreamUtil::CreateMemoryStreamWrite ( IXferBytes *  underlyingXferBytes, bool16  takeOwnership = kFalse, bool16  recycleBoss = kTrue  )

static

Open a stream for writing to memory.

Parameters

underlyingXferBytes	IXferBytes instance the memory stream will write to.
takeOwnership	Denotes whether the stream is to be the sole owner of the given IXferBytes.
recycleBoss	Denotes whether to utilize a recycle boss for the stream.\ If the underlying IXferBytes must be released to free up resources, a file for instance, it is recommended to not use a recycle boss since the IXferBytes might not be released until the stream boss is reused.

Returns

IPMStream* the new write stream

static IPMStream* StreamUtil::CreatePointerStreamRead ( char *  buffer, size_t  len  )

static

Open a stream for reading from memory.

Parameters

buffer	memory address to start reading from
len	number of bytes to read

Returns

IPMStream* the new stream.

static IPMStream* StreamUtil::CreatePointerStreamWrite ( char *  buffer, size_t  len  )

static

Open a stream for writing to memory.

Parameters

buffer	memory address to start writing to
len	number of bytes that can be written before end of stream

Returns

IPMStream* the new stream

static IPMStream* StreamUtil::CreateResourceStreamRead ( const RsrcSpec &  spec, bool16  useLocaleIndexResource = kTrue  )

static

Open a stream for reading from a resource.

Parameters

spec	a descriptor of the resource to read
useLocaleIndexResource	kTrue to use a localized resource

Returns

IPMStream* the new stream

static void StreamUtil::ResetStreamContentsChanged ( IPMStream *  )

inlinestatic

The following functions are used for verifying stream contents. They is debugging only because they are used to control assertions. There's an assert that comes up if an object has been modified, but Dirty() was never called on it ("object changed but not marked dirty"). The assert is for early detection of cases which could cause document corruption, but it does come up in some situations that are actually OK. For example, if your code does dynamic conversion of data, so that it gets converted when its read in, it would get this assert but be OK. Or if it writes out the current time. In any case, you can set a flag on the stream that causes the assert not to fire. From your ReadWrite, in the case where you're writing out, call SetStreamContentsChanged, and the assert will not come up.Set the stream back to normal after a call to SetStreamContentsChanged. Does nothing in Release target.

Parameters

s	the stream to set

static void StreamUtil::SetStreamContentsChanged ( IPMStream *  )

inlinestatic

Set the stream to "changes expected" to prevent the assert from firing. Does nothing in Release target.

Parameters

s	the stream to set

static bool16 StreamUtil::StreamContentsChanged ( IPMStream *  )

inlinestatic

Get the stream to "changes expected" to see if the assert should fire. Does nothing in Release target. Internal Use Only.

Parameters

s	the stream to set

Returns

bool16 return true if the stream has changes expected