All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
pdftron::Filters::Filter Class Reference

#include <Filter.h>

+ Inheritance diagram for pdftron::Filters::Filter:

Public Types

enum  ReferencePos { e_begin = SEEK_SET, e_end = SEEK_END, e_cur = SEEK_CUR }
 

Public Member Functions

 Filter ()
 
 ~Filter ()
 
 Filter (const Filter &copy)
 
Filteroperator= (const Filter &other)
 
 operator bool ()
 
void AttachFilter (Filter attach_filter)
 
Filter ReleaseAttachedFilter ()
 
Filter GetAttachedFilter ()
 
Filter GetSourceFilter ()
 
const char * GetName () const
 
const char * GetDecodeName () const
 
UCharBegin ()
 
size_t Size ()
 
void Consume (size_t num_bytes)
 
size_t Count ()
 
size_t SetCount (size_t new_count)
 
void SetStreamLength (size_t bytes)
 
void Flush ()
 
void FlushAll ()
 
bool IsInputFilter ()
 
bool CanSeek ()
 
void Seek (ptrdiff_t offset, ReferencePos origin)
 
ptrdiff_t Tell ()
 
Filter CreateInputIterator ()
 
const UString GetFilePath () const
 
void Destroy ()
 
void WriteToFile (const UString &path, bool append)
 

Detailed Description

Provides a generic view of a sequence of bytes.

A Filter is the abstract base class of all filters. A filter is an abstraction of a sequence of bytes, such as a file, an input/output device, an inter-process communication pipe, or a TCP/IP socket. The Filter class and its derived classes provide a generic view of these different types of input and output, isolating the programmer from the specific details of the operating system and the underlying devices.

Besides providing access to input/output sources Filters can be also to transform the data (e.g. to compress the data stream, to normalize the image data, to encrypt data, etc). Filters can also be attached to each other to form pipelines. For example, a filter used to open an image data file can be attached to a filter that decompresses the data, which is attached to another filter that will normalize the image data.

Depending on the underlying data source or repository, filters might support only some of these capabilities. An application can query a stream for its capabilities by using the IsInputFilter() and CanSeek() properties.

Note
To read or write data to a filter, a user will typically use FilterReader/FilterWriter class. instead of using Filter methods

For example:

* StdFile file("my_stream.txt", StdFile::e_read_mode);
* FilterReader reader(file);
* while (reader.Read(..)) ...
*

Definition at line 45 of file Filter.h.

Member Enumeration Documentation

Provides the fields that represent reference points in streams for seeking.

Enumerator
e_begin 
e_end 
e_cur 

Definition at line 172 of file Filter.h.

Constructor & Destructor Documentation

pdftron::Filters::Filter::Filter ( )
pdftron::Filters::Filter::~Filter ( )
pdftron::Filters::Filter::Filter ( const Filter copy)

Member Function Documentation

void pdftron::Filters::Filter::AttachFilter ( Filter  attach_filter)

Attaches a filter to the this filter. If this filter owns another filter it will be deleted. This filter then becomes the owner of the attached filter.

Parameters
attach_filterfilter object to attach
UChar* pdftron::Filters::Filter::Begin ( )
Returns
- beginning of the buffer of Size() bytes that can be used to read or write data.
bool pdftron::Filters::Filter::CanSeek ( )
Returns
- true if the stream supports seeking; otherwise, false. default is to return false.
void pdftron::Filters::Filter::Consume ( size_t  num_bytes)

Moves the Begin() pointer num_bytes forward.

Parameters
num_bytes- number of bytes to consume. num_bytes must be less than or equal to Size().
size_t pdftron::Filters::Filter::Count ( )
Returns
- the number of bytes consumed since opening the filter or the last Seek operation
Filter pdftron::Filters::Filter::CreateInputIterator ( )

Create Filter iterator. Filter iterator similar to a regular filter. However, there can be only one owner of the attached filter.

Note
- Derived classes should make sure that there is only one owner of the attached stream. Otherwise the attached stream may be deleted several times.
Exceptions
-throws an exception if the method is not implemented in the derived class
void pdftron::Filters::Filter::Destroy ( )

Frees the native memory of the object.

void pdftron::Filters::Filter::Flush ( )

Forces any data remaining in the buffer to be written to input or output filter.

void pdftron::Filters::Filter::FlushAll ( )

Forces any data remaining in the filter chain to the source or destination.

Filter pdftron::Filters::Filter::GetAttachedFilter ( )
Returns
- returns attached Filter or a NULL filter if no filter is attached.
const char* pdftron::Filters::Filter::GetDecodeName ( ) const
Returns
- string representing the name of corresponding decode filter as it should appear in document (e.g. both ASCIIHexDecode and ASCIIHexEncode should return ASCIIHexDecode).
const UString pdftron::Filters::Filter::GetFilePath ( ) const
Returns
the file path to the underlying file stream. Default implementation returns empty string.
const char* pdftron::Filters::Filter::GetName ( ) const
Returns
- descriptive name of the filter.
Filter pdftron::Filters::Filter::GetSourceFilter ( )
Returns
- returns the first filter in the chain (usually a file filter)
bool pdftron::Filters::Filter::IsInputFilter ( )
Returns
- boolean indicating whether this is an input filter.
pdftron::Filters::Filter::operator bool ( )
inline
Returns
true if the object is not null, false otherwise.

Definition at line 58 of file Filter.h.

Filter& pdftron::Filters::Filter::operator= ( const Filter other)
Filter pdftron::Filters::Filter::ReleaseAttachedFilter ( )

Release the ownership of the attached filter. After the attached filter is released this filter points to NULL filter.

Returns
- Previously attached filter.
void pdftron::Filters::Filter::Seek ( ptrdiff_t  offset,
ReferencePos  origin 
)

When overridden in a derived class, sets the position within the current stream.

Parameters
offset- A byte offset relative to origin. If offset is negative, the new position will precede the position specified by origin by the number of bytes specified by offset. If offset is zero, the new position will be the position specified by origin. If offset is positive, the new position will follow the position specified by origin by the number of bytes specified by offset.
origin- A value of type ReferencePos indicating the reference point used to obtain the new position
Note
- After each Seek() operation the number of consumed bytes (i.e. Count()) is set to 0.
Exceptions
-throws FilterExc if the method is not implemented in derived class
size_t pdftron::Filters::Filter::SetCount ( size_t  new_count)

Sets a new counting point for the current filter. All subsequent Consume() operations will increment this counter.

Make sure that the output filter is flushed before using SetCount().

Parameters
new_countnumber to set the counting point of the filter to.
Returns
- the value of previous counter
void pdftron::Filters::Filter::SetStreamLength ( size_t  bytes)

The functions specifies the length of the data stream. The default implementation doesn't do anything. For some derived filters such as file segment filter it may be useful to override this function in order to limit the stream length.

Parameters
bytesthe length of stream in bytes
size_t pdftron::Filters::Filter::Size ( )
Returns
- the size of buffer returned by Begin(). If the Size() returns 0 end of data has been reached.
ptrdiff_t pdftron::Filters::Filter::Tell ( )

Reports the current read position in the stream relative to the stream origin.

Returns
- The current position in the stream
Exceptions
-throws FilterExc if the method is not implemented in derived class
void pdftron::Filters::Filter::WriteToFile ( const UString path,
bool  append 
)

Writes the entire filter, starting at current position, to specified filepath. Should only be called on an input filter.

Parameters
paththe output filepath.
append'true' to append to existing file contents, 'false' to overwrite.

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