Struct ipworkszip::Lz4

Properties   Methods   Events   Config Settings   Errors  

The Lz4 struct implements an LZ4 compressor and decompressor.

Syntax

ipworkszip::Lz4

Remarks

The Lz4 struct is compliant with the LZ4 Frame Format specification. Data compressed by the struct can be decompressed by any standard LZ4-compatible tool or library, and the struct can in turn decompress data produced by any standard LZ4 encoder, including frames using linked blocks, block checksums, or skippable frames. Note that the legacy LZ4 frame format and LZ4 dictionaries are not supported, and frames using either are rejected with an error.

The compression_level property selects the compression level to use, from 1 (fastest) to 6 (most compact).

Data may be operated on in multiple ways as discussed below.

Compression and Decompression Streams

The get_decompression_stream and get_compression_stream methods are used to retrieve streams that read or write compressed data, as appropriate. The underlying stream should be passed to either method as a parameter.

CompressBlock and DecompressBlock

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

THe input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

CompressData and DecompressData

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksZip. Due to this, the Lz4 struct cannot be disposed of automatically. Please, call the dispose(&self) method of Lz4 when you have finished using the instance.

Property List

---

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

close_base_stream property (Lz4 Struct)

Whether or not to close the underlying stream.

Syntax

fn close_base_stream(&self) -> Result<bool, IPWorksZipError> 
fn set_close_base_stream(&self, value : bool) ->  Option<IPWorksZipError> 

Default Value

true

Remarks

This property controls whether streams created via the get_compression_stream and get_decompression_stream methods will close their underlying streams when their Close method is invoked.

When enabled, the underlying streams are closed; otherwise, they will remain open.

Data Type

bool

compression_level property (Lz4 Struct)

The compression level to use.

Syntax

fn compression_level(&self) -> Result<i32, IPWorksZipError> 
fn set_compression_level(&self, value : i32) ->  Option<IPWorksZipError> 

Default Value

4

Remarks

This property dictates the compression level to use, from 1 to 6. Higher values will cause the struct to compress better; lower values will cause the struct to compress faster.

Data Type

i32

input_data property (Lz4 Struct)

The data to compress or decompress.

Syntax

fn input_data(&self) -> Result<Vec<u8>, IPWorksZipError> 
fn set_input_data(&self, value : Vec<u8>) ->  Option<IPWorksZipError> 
fn set_input_data_ref(&self, value : &[u8]) ->  Option<IPWorksZipError> 

Default Value

""

Remarks

This property specifies the data to compress or decompress.

When decompressing, this should be set to the compressed data before the decompress_data or decompress_block methods are called.

When compressing, this should be set to the decompressed data before the compress_data or compress_block methods are called.

Note that this property is not automatically cleared after each operation when performing operations on multiple chunks of data.

Data Type

Vec<u8>

output_data property (Lz4 Struct)

The output data after compression or decompression.

Syntax

fn output_data(&self) -> Result<Vec<u8>, IPWorksZipError> 

Default Value

""

Remarks

This property holds the compressed or decompressed data after the compress_data or decompress_data methods are called.

This property is not applicable when calling the compress_block or decompress_block methods.

This property is read-only.

Data Type

Vec<u8>

compress_block method (Lz4 Struct)

Compresses a block of data.

Syntax

fn compress_block(&self, last_block : bool) -> Result<(), IPWorksZipError>

Remarks

This method compresses the block of data specified by the input_data property.

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

The input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

compress_data method (Lz4 Struct)

Compresses the specified data.

Syntax

fn compress_data(&self) -> Result<(), IPWorksZipError>

Remarks

This method compresses the data specified by the input_data property. After calling this method, the output_data property holds the compressed data.

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

config method (Lz4 Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) -> Result<String, IPWorksZipError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

decompress_block method (Lz4 Struct)

Decompresses a block of data.

Syntax

fn decompress_block(&self) -> Result<(), IPWorksZipError>

Remarks

This method decompresses the block of data specified by the input_data property.

The compress_block and decompress_block methods operate on blocks (chunks) of data. The methods may be used to compress and decompress data as they become available.

Note that when using blocks of data, the output_data property is not applicable. Instead, data are made available via the on_compressed_data and on_decompressed_data events.

If all data is available ahead of time, the compress_data and decompress_data methods may be called instead.

Compress Data

The input_data property should be set to the current block to be compressed. Next, the compress_block method should be called to compress the current block. Note that this method takes a LastBlock parameter; if the block of data is the final block to be compressed, it must be set to true. For all other blocks, it must remain false.

During compression, the on_compressed_data event will fire with the compressed data. Note that this event may not fire for every call to compress_block due to the way the compression algorithm operates.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressBlock(); Data are accumulated inside the on_compressed_data event: private static void Zipstream_OnCompressedData(object sender, ZipstreamCompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when compressing block data.

Decompress Data

The input_data property should be set to the current block to be decompressed. Next, the decompress_block method should be called to decompress the current block.

During decompression, the on_decompressed_data event will fire with the decompressed data. Note that this event may not fire for every call to decompress_block due to the way the decompression algorithm operates.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressBlock(); Data is accumulated inside the on_decompressed_data event: private static void Zipstream_OnDecompressedData(object sender, ZipstreamDecompressedDataEventArgs e) { DoSomethingWith(e.DataB); }

Note that the output_data property is not applicable when decompressing block data.

decompress_data method (Lz4 Struct)

Decompresses the specified data.

Syntax

fn decompress_data(&self) -> Result<(), IPWorksZipError>

Remarks

This method decompresses the data specified by the input_data property. After calling this method, the output_data property holds the decompressed data.

The compress_data and decompress_data methods operate on the complete blob of data. The entire compressed or decompressed data must be set to the input_data property before calling either method.

To compress and decompress data in blocks (chunks), refer to the compress_block and decompress_block methods.

Compress Data

The input_data property should be set to the decompressed data. This should be the entire data to be compressed. Next, the compress_data method should be called, after which the output_data property will hold the compressed data.

zipstream.InputDataB = MyDecompressedData; zipstream.CompressData(); MyCompressedData = zipstream.OutputDataB;

In addition to output_data, the compressed data may also be accumulated within the on_compressed_data event.

Decompress Data

The input_data property should be set to the compressed data. This should be the entire data to be decompressed. Next, the decompress_data method should be called, after which the output_data property will hold the decompressed data.

zipstream.InputDataB = MyCompressedData; zipstream.DecompressData(); MyDecompressedData = zipstream.OutputDataB;

In addition to output_data, the decompressed data may also be accumulated within the on_decompressed_data event.

reset method (Lz4 Struct)

Resets the struct.

Syntax

fn reset(&self) -> Result<(), IPWorksZipError>

Remarks

This method is used to reset the state of the struct. All properties are set to their default values, and any open files are closed.

on_compressed_data event (Lz4 Struct)

Fires with compressed data.

Syntax

// Lz4CompressedDataEventArgs carries the Lz4 CompressedData event's parameters.
pub struct Lz4CompressedDataEventArgs {
  fn data(&self) -> &[u8]
}

// Lz4CompressedDataEvent defines the signature of the Lz4 CompressedData event's handler function.
pub trait Lz4CompressedDataEvent {
  fn on_compressed_data(&self, sender : Lz4, e : &mut Lz4CompressedDataEventArgs);
}

impl <'a> Lz4<'a> {
  pub fn on_compressed_data(&self) -> &'a dyn Lz4CompressedDataEvent;
  pub fn set_on_compressed_data(&mut self, value : &'a dyn Lz4CompressedDataEvent);
  ...
}

Remarks

This event is fired one or more times as compressed data become available when the compress_data or compress_block methods are called.

Data holds the current block of compressed data.

on_decompressed_data event (Lz4 Struct)

Fires with decompressed data.

Syntax

// Lz4DecompressedDataEventArgs carries the Lz4 DecompressedData event's parameters.
pub struct Lz4DecompressedDataEventArgs {
  fn data(&self) -> &[u8]
}

// Lz4DecompressedDataEvent defines the signature of the Lz4 DecompressedData event's handler function.
pub trait Lz4DecompressedDataEvent {
  fn on_decompressed_data(&self, sender : Lz4, e : &mut Lz4DecompressedDataEventArgs);
}

impl <'a> Lz4<'a> {
  pub fn on_decompressed_data(&self) -> &'a dyn Lz4DecompressedDataEvent;
  pub fn set_on_decompressed_data(&mut self, value : &'a dyn Lz4DecompressedDataEvent);
  ...
}

Remarks

This event is fired one or more times as decompressed data become available when the decompress_data or decompress_block methods are called.

Data holds the current block of decompressed data.

on_error event (Lz4 Struct)

Fires with information about errors during data delivery.

Syntax

// Lz4ErrorEventArgs carries the Lz4 Error event's parameters.
pub struct Lz4ErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// Lz4ErrorEvent defines the signature of the Lz4 Error event's handler function.
pub trait Lz4ErrorEvent {
  fn on_error(&self, sender : Lz4, e : &mut Lz4ErrorEventArgs);
}

impl <'a> Lz4<'a> {
  pub fn on_error(&self) -> &'a dyn Lz4ErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn Lz4ErrorEvent);
  ...
}

Remarks

This event is fired in case of exceptional conditions during message processing. Normally, the struct fails with an error.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (Lz4 Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

No configuration settings defined.

Base Config Settings

Trappable Errors (Lz4 Struct)

Note that the streams returned by get_compression_stream and get_decompression_stream will throw standard IOExceptions in case of error.

ZipStream Errors