Celartem::DjVu::Chunk Class Reference

#include <djv_chunks.h>

Inheritance diagram for Celartem::DjVu::Chunk:

[legend]

List of all members.

Public Types
typedef SimpleArray< AutoPtr < Chunk > >	Array
typedef void(*	OnChunkCallback )(void *inContext, Chunk *inChunkLoaded)
Public Member Functions
virtual String	getId () const =0
virtual AutoPtr< const Data >	getData () const =0
virtual AutoPtr< Data >	getData ()=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	assureImmediateResponse (OnChunkCallback inOnChunkCallback=NULL, void *inContext=NULL)=0
virtual void	prepareForMerger (Chunk *inChunkMergeTo, std::map< String, String > *outNameRemappings=NULL, bool inDoingAutoNavmAnnoRemapping=true)=0
virtual void	compact ()=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	getNameInDIRM () const =0
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)

---

Detailed Description

An abstract class which defines the requirements for chunks.
Please note that the methods on a 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 lock or using Locker class) before manipulation on it. The following code illustrates this:

    Locker lock(*chunk);
    chunk->getChildren().push_back(...);

Definition at line 39 of file djv_chunks.h.

---

Member Typedef Documentation

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

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

Definition at line 129 of file djv_chunks.h.

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

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

Parameters:

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

---

Member Function Documentation

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 String Celartem::DjVu::Chunk::getId

(

)

const [pure virtual]

Get the identifier of this chunk.

Returns:

The 4 character IFF chunk identifier.

virtual AutoPtr<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 AutoPtr<Data> Celartem::DjVu::Chunk::getData

(

)

[pure virtual]

Get the associated Data instance.

Returns:

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

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 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 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 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 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 assureImmediateResponse.

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 void Celartem::DjVu::Chunk::assureImmediateResponse	(	OnChunkCallback	inOnChunkCallback = NULL,
		void *	inContext = NULL
	)			[pure virtual]

Load all the data to the memory and disconnect from any external resources.
When overwriting the original file from which the chunks are loaded, some of the chunk may not be loaded onto the memory and take the references to the original file. In such situation, assureImmediateResponse make sure that all the chunks are loaded onto the memory and completely disconnected from the original file.

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	(	Chunk *	inChunkMergeTo,
		std::map< String, String > *	outNameRemappings = NULL,
		bool	inDoingAutoNavmAnnoRemapping = true
	)			[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.

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.

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.
This method also make sure that all the data is on memory as if assureImmediateResponse were called.

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 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 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::unlock

(

)

const [pure virtual]

Release the lock on the instance.

See also:

lock, Locker, Lockable

Implements Celartem::Lockable.

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::getNameInDIRM

(

)

const [pure virtual]

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

Returns:

The name in DIRM if available; otherwise NullString.

---

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

• djv_chunks.h

---

This document is automatically generated using doxygen 1.5.4 at Fri Jun 27 18:23:25 2008.