Public Member Functions | Private Member Functions | List of all members
StreamConversionInterface Class Reference

#include <streamconversion.h>

Inheritance diagram for StreamConversionInterface:
Inheritance graph
[legend]

Detailed Description

StreamConversionInterface is a universal interface to convert data. It can be used for Encryption, Compression, Encoding, Hashing, basically everything that streams data in and out.

Public Member Functions

MAXON_METHOD Int GetBatchSize () const
 
MAXON_METHOD Int GetBlockSize () const
 
MAXON_METHOD Id GetCounterpart () const
 
MAXON_METHOD const DataType & GetSourceType () const
 
MAXON_METHOD const DataType & GetDestinationType () const
 
MAXON_METHOD Bool SupportInplaceConversion () const
 
MAXON_METHOD Result< Int > ConvertImpl (const Block< const Generic > &src, WritableArrayInterface< Generic > &dst, Int dstLimitHint, Bool inputFinished, Bool &outputFinished)
 
template<typename SRC , typename DST >
MAXON_FUNCTION Result< Int > Convert (const SRC &src, DST &dst, Int dstLimitHint, Bool inputFinished, Bool &outputFinished)
 
template<typename SRC , typename DST >
MAXON_FUNCTION Result< void > ConvertAll (const SRC &src, DST &dst, Int dstLimitHint=1<< 16)
 
template<typename SRC >
MAXON_FUNCTION Result< void > ConvertAllInplace (const SRC &data)
 
MAXON_METHOD Result< InputStreamRef > ConvertToStream (const InputStreamRef &in)
 
MAXON_METHOD Result< InputStreamRef > ConvertToStream (const DataFormatBaseReaderRef &in)
 
MAXON_METHOD Result< DataFormatBaseReaderRef > ConvertToReader (const InputStreamRef &in)
 
MAXON_METHOD Result< DataFormatBaseReaderRef > ConvertToReader (const DataFormatBaseReaderRef &in)
 
MAXON_METHOD Result< OutputStreamRef > ConvertToStream (const OutputStreamRef &out)
 
MAXON_METHOD Result< OutputStreamRef > ConvertToStream (const DataFormatBaseWriterRef &out)
 
MAXON_METHOD Result< DataFormatBaseWriterRef > ConvertToWriter (const OutputStreamRef &out)
 
MAXON_METHOD Result< DataFormatBaseWriterRef > ConvertToWriter (const DataFormatBaseWriterRef &out)
 

Private Member Functions

 MAXON_INTERFACE (StreamConversionInterface, MAXON_REFERENCE_NORMAL, "net.maxon.interface.streamconversion", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel"))
 

Member Function Documentation

◆ MAXON_INTERFACE()

MAXON_INTERFACE ( StreamConversionInterface  ,
MAXON_REFERENCE_NORMAL  ,
"net.maxon.interface.streamconversion"  ,
MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")   
)
private

◆ GetBatchSize()

MAXON_METHOD Int GetBatchSize ( ) const

Returns the recommended working size.

◆ GetBlockSize()

MAXON_METHOD Int GetBlockSize ( ) const

Returns the block size in of the encoder/decoder. The encoded/decoded data needs to be a multiple of GetBlockSize(). This number is the count of elements of GetSourceType(), not the size in bytes!

◆ GetCounterpart()

MAXON_METHOD Id GetCounterpart ( ) const

Returns the corresponding Stream converter id.

◆ GetSourceType()

MAXON_METHOD const DataType& GetSourceType ( ) const

Returns the source data type which is accepted by this stream converter.

◆ GetDestinationType()

MAXON_METHOD const DataType& GetDestinationType ( ) const

Returns the destination data type which is accepted by this stream converter.

◆ SupportInplaceConversion()

MAXON_METHOD Bool SupportInplaceConversion ( ) const

Returns true if the StreamConversionRef supports in-place conversion which means that source and destination pointers might be identical. If true is returned it's possible to call ConvertAllInplace().

◆ ConvertImpl()

MAXON_METHOD Result<Int> ConvertImpl ( const Block< const Generic > &  src,
WritableArrayInterface< Generic > &  dst,
Int  dstLimitHint,
Bool  inputFinished,
Bool &  outputFinished 
)

Converts (part of) the source data in src to dst. The stream conversion need not consume all of src, therefore it returns the number of actually consumed elements. The unconsumed elements should be passed to the stream conversion in the next invocation of ConvertImpl.

Note: A StreamConversionInterface can be used only once! If you want to convert multiple streams you have to allocate a StreamConversionInterface for each Convert call.

If inputFinished is false, this indicates that the source data src is only a part of the whole data, so further data may be passed to the stream conversion by further invocations of ConvertImpl. If inputFinished is true, then src is the last part of the whole data. Even then further invocations of ConvertImpl might be necessary, for example if dstLimitHint hinders the stream conversion to write the complete output to dst. If the call returns true in outputFinished this means that no further calls must happen. Usually this happens only if inputFinished was set to true.

So to ensure that the stream conversion has finished, you have to set inputFinished to true and invoke ConsumeImpl as long as outputFinished returns with false.

Stream converters which request a GetBlockSize() > 1 needs the data for one block in one chunk. So if there is not enough data delivered the functions returns '0' to request more input bytes. The caller needs to ensure that more data comes within this block. The ConvertAll() function respects this already and copies the data into a temp array.

Parameters
[in]srcInput data. The element size has to match the size of the source type.
[out]dstArray to append the converted data to. New data will be appended to the end, so previously existing array elements are kept. The element size has to match the size of the destination type.
[in]dstLimitHintA hint to the stream conversion about the maximum number of elements to add to dst in a single invocation of ConvertImpl. The stream conversion should not exceed this limit by a large amount if possible.
[in]inputFinishedIf true, the data in src is the last part of the whole input data.
[out]outputFinishedIf true, the data in dst was the last part of the conversion.
Returns
Number of elements which the stream conversion has consumed from src.

◆ Convert()

MAXON_FUNCTION Result<Int> Convert ( const SRC &  src,
DST &  dst,
Int  dstLimitHint,
Bool  inputFinished,
Bool &  outputFinished 
)

Converts (part of) the source data in src to dst. The stream conversion need not consume all of src, therefore it returns the number of actually consumed elements. The unconsumed elements should be passed to the stream conversion in the next invocation of ConvertImpl.

Note: A StreamConversionInterface can be used only once! If you want to convert multiple streams you have to allocate a StreamConversionInterface for each Convert call.

If inputFinished is false, this indicates that the source data src is only a part of the whole data, so further data may be passed to the stream conversion by further invocations of ConvertImpl. If inputFinished is true, then src is the last part of the whole data. Even then further invocations of ConvertImpl might be necessary, for example if dstLimitHint hinders the stream conversion to write the complete output to dst. If the call returns true in outputFinished this means that no further calls must happen. Usually this happens only if inputFinished was set to true.

So to ensure that the stream conversion has finished, you have to set inputFinished to true and invoke ConsumeImpl as long as outputFinished returns with false.

Stream converters which request a GetBlockSize() > 1 needs the data for one block in one chunk. So if there is not enough data delivered the functions returns '0' to request more input bytes. The caller needs to ensure that more data comes within this block. The ConvertAll() function respects this already and copies the data into a temp array.

Parameters
[in]srcInput data. The element size has to match the size of the source type.
[out]dstArray to append the converted data to. New data will be appended to the end, so previously existing array elements are kept. The element size has to match the size of the destination type.
[in]dstLimitHintA hint to the stream conversion about the maximum number of elements to add to dst in a single invocation of ConvertImpl. The stream conversion should not exceed this limit by a large amount if possible.
[in]inputFinishedIf true, the data in src is the last part of the whole input data.
[out]outputFinishedIf true, the data in dst was the last part of the conversion.
Returns
Number of elements which the stream conversion has consumed from src.

◆ ConvertAll()

MAXON_FUNCTION Result<void> ConvertAll ( const SRC &  src,
DST &  dst,
Int  dstLimitHint = 1 << 16 
)

Converts the complete source data in src to dst. The conversion will consume all of src.

Parameters
[in]srcInput data. The element size has to match the size of the source type.
[out]dstArray to append the converted data to. New data will be appended to the end, so previously existing array elements are kept. The element size has to match the size of the destination type.
[in]dstLimitHintA hint to the stream conversion about the maximum number of elements to add to dst in a single invocation of ConvertImpl. The stream conversion should not exceed this limit by a large amount if possible.
Returns
OK on success.

Note: A StreamConversionInterface can be used only once! If you want to convert multiple streams you have to allocate a StreamConversionInterface for each Convert call.

◆ ConvertAllInplace()

MAXON_FUNCTION Result<void> ConvertAllInplace ( const SRC &  data)

Converts the complete source data in data and overwrites the data in data. The conversion will consume all of data.

Parameters
[in,out]dataInput/Output data. The element size has to match the size of the source type.
Returns
OK on success.

Note: A StreamConversionInterface can be used only once! If you want to convert multiple streams you have to allocate a StreamConversionInterface for each Convert call.

◆ ConvertToStream() [1/4]

MAXON_METHOD Result<InputStreamRef> ConvertToStream ( const InputStreamRef &  in)

◆ ConvertToStream() [2/4]

MAXON_METHOD Result<InputStreamRef> ConvertToStream ( const DataFormatBaseReaderRef &  in)

◆ ConvertToReader() [1/2]

MAXON_METHOD Result<DataFormatBaseReaderRef> ConvertToReader ( const InputStreamRef &  in)

◆ ConvertToReader() [2/2]

MAXON_METHOD Result<DataFormatBaseReaderRef> ConvertToReader ( const DataFormatBaseReaderRef &  in)

◆ ConvertToStream() [3/4]

MAXON_METHOD Result<OutputStreamRef> ConvertToStream ( const OutputStreamRef &  out)

◆ ConvertToStream() [4/4]

MAXON_METHOD Result<OutputStreamRef> ConvertToStream ( const DataFormatBaseWriterRef &  out)

◆ ConvertToWriter() [1/2]

MAXON_METHOD Result<DataFormatBaseWriterRef> ConvertToWriter ( const OutputStreamRef &  out)

◆ ConvertToWriter() [2/2]

MAXON_METHOD Result<DataFormatBaseWriterRef> ConvertToWriter ( const DataFormatBaseWriterRef &  out)