PTFilter

@interface PTFilter : NSObject

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(..)) ...

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

    Declaration

    Objective-C

    - (void)AttachFilter:(PTFilter *)attach_filter;

    Swift

    func attach(_ attach_filter: PTFilter!)

    Parameters

    attach_filter

    filter object to attach

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

    Declaration

    Objective-C

    - (PTFilter *)ReleaseAttachedFilter;

    Swift

    func releaseAttached() -> PTFilter!

    Return Value

    - Previously attached filter.

  • Declaration

    Objective-C

    - (PTFilter *)GetAttachedFilter;

    Swift

    func getAttached() -> PTFilter!

    Return Value

    - returns attached Filter or a NULL filter if no filter is attached.

  • Declaration

    Objective-C

    - (PTFilter *)GetSourceFilter;

    Swift

    func getSource() -> PTFilter!

    Return Value

    - returns the first filter in the chain (usually a file filter)

  • Declaration

    Objective-C

    - (NSString *)GetName;

    Swift

    func getName() -> String!

    Return Value

    - descriptive name of the filter.

  • Declaration

    Objective-C

    - (NSString *)GetDecodeName;

    Swift

    func getDecodeName() -> String!

    Return Value

    - string representing the name of corresponding decode filter as it should appear in document (e.g. both ASCIIHexDecode and ASCIIHexEncode should return ASCIIHexDecode).

  • Declaration

    Objective-C

    - (unsigned long)Size;

    Swift

    func size() -> UInt

    Return Value

    - the size of buffer returned by Begin(). If the Size() returns 0 end of data has been reached.

  • Moves the Begin() pointer num_bytes forward.

    Declaration

    Objective-C

    - (void)Consume:(unsigned long)num_bytes;

    Swift

    func consume(_ num_bytes: UInt)

    Parameters

    num_bytes

    - number of bytes to consume. num_bytes must be less than or equal to Size().

  • Declaration

    Objective-C

    - (unsigned long)Count;

    Swift

    func count() -> UInt

    Return Value

    - the number of bytes consumed since opening the filter or the last Seek operation

  • 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().

    Declaration

    Objective-C

    - (unsigned long)SetCount:(unsigned long)new_count;

    Swift

    func setCount(_ new_count: UInt) -> UInt

    Parameters

    new_count

    number to set the counting point of the filter to.

    Return Value

    - the value of previous counter

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

    Declaration

    Objective-C

    - (void)SetStreamLength:(unsigned long)bytes;

    Swift

    func setStreamLength(_ bytes: UInt)

    Parameters

    bytes

    the length of stream in bytes

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

    Declaration

    Objective-C

    - (void)Flush;

    Swift

    func flush()

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

    Declaration

    Objective-C

    - (void)FlushAll;

    Swift

    func flushAll()

  • Declaration

    Objective-C

    - (BOOL)IsInputFilter;

    Swift

    func isInputFilter() -> Bool

    Return Value

    - boolean indicating whether this is an input filter.

  • Declaration

    Objective-C

    - (BOOL)CanSeek;

    Swift

    func canSeek() -> Bool

    Return Value

    - true if the stream supports seeking; otherwise, false. default is to return false.

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

    Note

    - After each Seek() operation the number of consumed bytes (i.e. Count()) is set to 0.

    @exception - throws FilterExc if the method is not implemented in derived class

    Declaration

    Objective-C

    - (void)Seek:(unsigned long long)offset origin:(PTReferencePos)origin;

    Swift

    func seek(_ offset: UInt64, origin: PTReferencePos)

    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

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

    Declaration

    Objective-C

    - (unsigned long long)Tell;

    Swift

    func tell() -> UInt64

    Return Value

    - The current position in the stream @exception - throws FilterExc if the method is not implemented in derived class

  • Truncates the underlying data.

    This method is for a writeable, seekable filter only and will throw otherwise.

    Note

    For a filter representing a file, truncation would mean resizing the file.

    Declaration

    Objective-C

    - (unsigned long)Truncate:(unsigned long)new_size;

    Swift

    func truncate(_ new_size: UInt) -> UInt

    Parameters

    new_size

    - the number of bytes to resize the filter to

    Return Value

    - The new size of the filter @exception - throws FilterExc if the method is not implemented in derived class

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

    @exception - throws an exception if the method is not implemented in the derived class

    Declaration

    Objective-C

    - (PTFilter *)CreateInputIterator;

    Swift

    func createInputIterator() -> PTFilter!

  • Declaration

    Objective-C

    - (NSString *)GetFilePath;

    Swift

    func getFilePath() -> String!

    Return Value

    the file path to the underlying file stream. Default implementation returns empty string.

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

- parameter: path the output filepath.
- parameter: append 'true' to append to existing file contents, 'false' to overwrite.

    Declaration

    Objective-C

    - (void)WriteToFile:(NSString *)path append:(BOOL)append;

    Swift

    func write(toFile path: String!, append: Bool)

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)init;

    Swift

    init!()