#include <djv_chunks.h>

Inheritance diagram for Celartem::DjVu::Chunk:

Public Types
enum	DisconnectMethod { dm_OnMemory = 0, dm_OnTempFile = 1, dm_AllOnTempFile = 2 }

typedef SimpleArray< AutoPtr < Chunk > >	Array

typedef void(*	OnChunkCallback )(void inContext, Chunk inChunkLoaded)

typedef String(*	RenameFunc )(void inContext, const String &inOldName, const Chunk inTarget, size_t inTrial)

Public Member Functions
virtual String	getId () const =0

virtual const Data *	getData () const =0

virtual void	setData (const Data *inData)=0

virtual const Array &	getChildren () const =0

virtual Array &	getChildren ()=0

virtual size_t	find (const String &inIdentifier, size_t inPrevPos=(size_t) 0-1, bool inOnlyAvailable=false) const =0

virtual size_t	find (const String &inId1, const String &inId2, size_t inPrevPos=(size_t) 0-1, bool inOnlyAvailable=false) const =0

virtual bool	isIncluded () const =0

virtual bool	isAvailable () const =0

virtual bool	isCollection () const =0

virtual void	preload (OnChunkCallback inOnChunkCallback=NULL, void *inContext=NULL)=0

virtual void	prepareForMerger (const Chunk inChunkMergeTo, std::map< String, String > outNameRemappings=NULL, bool inDoingAutoNavmAnnoRemapping=true, RenameFunc inRenameFunc=NULL, void *inRenameContext=NULL)=0

virtual void	compact ()=0

virtual void	disconnectFromOriginalSources (DisconnectMethod inDisconnectMethod=dm_OnTempFile, OnChunkCallback inOnChunkCallback=NULL, void inContext=NULL, Storage inTemporaryStorage=NULL)=0

virtual void	setSecurityProvider (const SecurityProvider *inSecProv)=0

virtual const SecurityProvider *	getSecurityProvider () const =0

virtual void	lock () const =0

virtual void	unlock () const =0

virtual Chunk *	getDirectPointer ()=0

virtual String	getName () const =0

Public Member Functions inherited from Celartem::Referable
	Referable ()

void	addRef () const

void	releaseRef () const

size_t	getReferenceCount () const

Static Public Member Functions
static AutoPtr< Chunk >	create (const String &inIdentifier)

static AutoPtr< Chunk >	create (const String &inIdentifier, const void *inData, size_t inDataSize)

static AutoPtr< Chunk >	create (const String &inIdentifier, Stream *inDataStream)

static AutoPtr< Chunk >	createCollection (const String &inIdentifier)

Static Public Member Functions inherited from Celartem::Referable
static void	dumpDbgAllRefCount ()

Detailed Description

        An abstract class which defines the requirements for chunks.\n
        Please note that the methods on a \ref Chunk instance is not
        serialized; they're not thread-safe. If you want to use the same
        instance between threads, you should lock the instance
        (by calling \ref lock or using \ref Locker class)
        before manipulation on it. The following code illustrates this:

Locker lock(*chunk);

chunk->getChildren().push_back(...);

Member Typedef Documentation

typedef SimpleArray<AutoPtr<Chunk> > Celartem::DjVu::Chunk::Array

Definition of Array which is usually used for accessing each child Chunk element.

typedef void(* Celartem::DjVu::Chunk::OnChunkCallback)(void *inContext, Chunk *inChunkLoaded)

Callback definition used by preload method.
During preload call, this callback is called when each chunk is loaded.

Parameters

inContext	The context passed to the second parameter of preload method.
inChunkLoaded	The chunk which is just loaded.

typedef String(* Celartem::DjVu::Chunk::RenameFunc)(void *inContext, const String &inOldName, const Chunk *inTarget, size_t inTrial)

Function definition for chunk renaming on prepareForMerger call.

Parameters

inContext	The parameter renameContext passed to prepareForMerger call.
inOldName	The old name of the rename target chunk.
inTarget	The rename target chunk.
inTrial	A number which indicates how much calls before this call for this chunk. This method may be called repeatedly if the name returned on the previous call returns a name which does not fit to the situation (such as name already exists or invalid characters in the name, ...).

Member Enumeration Documentation

enum Celartem::DjVu::Chunk::DisconnectMethod

Disconnect method used by disconnectFromOriginalSource method.

See Also: disconnectFromOriginalSources

Enumerator
dm_OnMemory	Place all the data on memory.
dm_OnTempFile	Move data connected to external storages to memory.
dm_AllOnTempFile	Move any data to temporary file.

Member Function Documentation

virtual void Celartem::DjVu::Chunk::compact ( )

pure virtual

Minimize the memory usage by removing reserved area.
This is useful when reducing memory fragmentation due to complicated process.

See Also: disconnectFromOriginalSources

static AutoPtr<Chunk> Celartem::DjVu::Chunk::create ( const String & inIdentifier )

static

Create a Chunk instance.

Parameters

inIdentifier 4 character identifier used with the newly created chunk.

Returns: Pointer to the newly created Chunk instance.

Referenced by Celartem::DjVu::PageInfo::encodeINFOChunk().

static AutoPtr<Chunk> Celartem::DjVu::Chunk::create	(	const String &	inIdentifier,
		const void *	inData,
		size_t	inDataSize
	)

static

Create a Chunk instance.

Parameters

inIdentifier	4 character identifier used with the newly created chunk.
inData	The data to be associated. Please note that this data is duplicated to the newly created Chunk instance.
inDataSize	The size of the data.

Returns: Pointer to the newly created Chunk instance.

static AutoPtr<Chunk> Celartem::DjVu::Chunk::create	(	const String &	inIdentifier,
		Stream *	inDataStream
	)

static

Create a Chunk instance.

Parameters

inIdentifier	4 character identifier used with the newly created chunk.
inDataStream	The data to be associated. Please note that this Stream instance is duplicated to the newly created Chunk instance.

Returns: Pointer to the newly created Chunk instance.

static AutoPtr<Chunk> Celartem::DjVu::Chunk::createCollection ( const String & inIdentifier )

static

Create a collection Chunk instance, which can contain multiple Chunk instance in it.

Parameters

inIdentifier 4 character identifier used with the newly created chunk.

Returns: Pointer to the newly created Chunk instance.

virtual void Celartem::DjVu::Chunk::disconnectFromOriginalSources	(	DisconnectMethod	inDisconnectMethod = `dm_OnTempFile`,
		OnChunkCallback	inOnChunkCallback = `NULL`,
		void *	inContext = `NULL`,
		Storage *	inTemporaryStorage = `NULL`
	)

pure virtual

This method ensures that the original source file is released and all the data referenced from the chunk is moved to other safe storage (memory or some temporary file).
It ensures the source file can be modified, overwritten or deleted.

Parameters

Method	to disconnect from the original sources.
inOnChunkCallback	Pointer to a callback function which will be called when each chunk is loaded.
inContext	A user defined data which is passed to the callback function.
inTemporaryStorage	Specify the external temporary storage instance if inDisconnectMethod is one of dm_OnTempFile or dm_AllOnTempFile. It can be `NULL` if you don't have to specify temporary storage explicitly.

See Also: compact, preload

virtual size_t Celartem::DjVu::Chunk::find	(	const String &	inIdentifier,
		size_t	inPrevPos = `(size_t) 0-1`,
		bool	inOnlyAvailable = `false`
	)		const

pure virtual

Search for the specified chunk.

Parameters

inIdentifier	The chunk identifier such as `DJVU`, `INFO`.
inPrevPos	The index returned by the previous call to this method. To start search from the first element, set (size_t)-1 for this. This is useful when finding multiple occurrences of the chunks such as `BG44`.
inOnlyAvailable	If this is `true`, this method searchs only available chunks (For more about available chunks, see isAvailable method.

Returns: The index of the element. If no occurence found, the method returns (size_t)-1.

virtual size_t Celartem::DjVu::Chunk::find	(	const String &	inId1,
		const String &	inId2,
		size_t	inPrevPos = `(size_t) 0-1`,
		bool	inOnlyAvailable = `false`
	)		const

pure virtual

Search for the specified chunk.
This is a special version which takes two identifiers and returns the occurrence of either inId1 or inId2.
Some of the DjVu chunks such as TXTz and ANTz have uncompressed versions; TXTa and ANTa. This method is designed for searching such kind of chunks.

Parameters

inId1	The chunk identifier.
inId2	The chunk identifier.
inPrevPos	The index returned by the previous call to this method. To start search from the first element, set (size_t)-1 for this. This is useful when finding multiple occurrences of the chunks such as `BG44`.
inOnlyAvailable	If this is `true`, this method searchs only available chunks (For more about available chunks, see isAvailable method.

Returns: The index of the element. If no occurence found, the method returns (size_t)-1.

virtual const Array& Celartem::DjVu::Chunk::getChildren ( ) const

pure virtual

Get the child elements. (const version)

Returns: Reference to the readonly Array instance.
If this is not a collection (a.k.a. FORM) chunk, this method throws an exception.

If you want to use a Chunk instance between threads, you should firstly aquire the lock of the instance and then use the returned Array instance.

Lock lock(*chunk);
Array& array = getChildren();
...
lock.unlock(); // or just get out of the scope

virtual Array& Celartem::DjVu::Chunk::getChildren ( )

pure virtual

Get the child elements.

Returns: Reference to the Array instance. If this is not a collection (a.k.a. FORM) chunk, this method throws an exception.

If you want to use a Chunk instance between threads, you should firstly aquire the lock of the instance and then use the returned Array instance.

Lock lock(*chunk);
Array& array = getChildren();
...
lock.unlock(); // or just get out of the scope

virtual const Data* Celartem::DjVu::Chunk::getData ( ) const

pure virtual

Get the associated Data instance. (const version)

Returns: Data assigned to this chunk. It may be NULL if no data is assigned.

Referenced by Celartem::DjVu::PageInfo::decode().

virtual Chunk* Celartem::DjVu::Chunk::getDirectPointer ( )

pure virtual

Get the direct (raw) pointer to the actual Chunk instance.

Returns: Pointer to the actual Chunk instance.

virtual String Celartem::DjVu::Chunk::getId ( ) const

pure virtual

Get the identifier of this chunk.

Returns: The 4 character IFF chunk identifier.

virtual String Celartem::DjVu::Chunk::getName ( ) const

pure virtual

Get the name for this chunk, which is listed in DIRM if available.

Returns: The name if available; otherwise NullString.

virtual const SecurityProvider* Celartem::DjVu::Chunk::getSecurityProvider ( ) const

pure virtual

Get the SecurityProvider instance associated to this chunk.

Returns: Pointer to the SecurityProvider instance if associated; otherwise NULL.

virtual bool Celartem::DjVu::Chunk::isAvailable ( ) const

pure virtual

Determine whether the chunk data is already available or not.
This method determines whether all the data of the chunk is loaded onto the memory or not. To make sure all of them are on memory, use preload.

Returns: true if the data is already available; otherwise false.

virtual bool Celartem::DjVu::Chunk::isCollection ( ) const

pure virtual

Determine whether the instance is a collection or not.

Returns: true if this is a collection instance; otherwise false.

virtual bool Celartem::DjVu::Chunk::isIncluded ( ) const

pure virtual

Determine whether the chunk is included by INCL indirection chunk or not.

Returns: true if the chunk is included by INCL; otherwise false.

virtual void Celartem::DjVu::Chunk::lock ( ) const

pure virtual

Lock the instance.
This method provides a synchronization mechanism for processing the instance between threads.
If you plan to use the instance in multi-threaded program, it's recommended to lock the instance before accessing the data.

See Also: unlock, Locker, Lockable

Implements Celartem::Lockable.

virtual void Celartem::DjVu::Chunk::preload	(	OnChunkCallback	inOnChunkCallback = `NULL`,
		void *	inContext = `NULL`
	)

pure virtual

Load all the data synchronously.
This method ensures that all the data and descending chunks are ready to use.

Parameters

inOnChunkCallback	Pointer to a callback function which will be called when each chunk is loaded.
inContext	A user defined data which is passed to the callback function.

virtual void Celartem::DjVu::Chunk::prepareForMerger	(	const Chunk *	inChunkMergeTo,
		std::map< String, String > *	outNameRemappings = `NULL`,
		bool	inDoingAutoNavmAnnoRemapping = `true`,
		RenameFunc	inRenameFunc = `NULL`,
		void *	inRenameContext = `NULL`
	)

pure virtual

Prepare for the merger with the specified DJVM chunk. Each DJVU chunks are usually managed by a name and if multiple DjVu files are merged into a DjVu file, it may cause some confliction in names. This method renames such chunks before the actual merge process. This method also removes shared annotation to reduce confliction with the merger document.

Parameters

inChunkMergeTo	Pointer to a `DJVM` Chunk instance to merge with.
outNameRemappings	A map instance which receives name remapping list (old to new) for further process. It can be `NULL` if you don't need such information.
inDoingAutoNavmAnnoRemapping	`true` to instruct this method to do updating `NAVM` and `ANTz`, `ANTa` chunks.
inRenameFunc	Optional function to rename chunks.
inRenameContext	Optional parameter, which is passed to rename function.

virtual void Celartem::DjVu::Chunk::setData ( const Data * inData )

pure virtual

Set the data to this chunk. The Data instance passed is retained by this Chunk instance.

Parameters

inData Data to assign.

virtual void Celartem::DjVu::Chunk::setSecurityProvider ( const SecurityProvider * inSecProv )

pure virtual

Set a SecurityProvider instance to this chunk.
Only collection chunk can have SecurityProvider.

Parameters

inSecProv Pointer to a SecurityProvider instance.

virtual void Celartem::DjVu::Chunk::unlock ( ) const

pure virtual

Release the lock on the instance.

See Also: lock, Locker, Lockable

Implements Celartem::Lockable.

The documentation for this class was generated from the following file:

djv_chunks.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation