Class DataSegment

Namespace

Net.Codecrete.QrCodeGenerator

Assembly

QrCodeGenerator.dll

A chunk of payload data to be carried by the QR code.

The payload data carried by a QR code is a sequence of data segments. Each segment is a sequence of bytes encoded with a specific encoding mode: numeric, alphanumeric, Kanji, or binary. Additionally, a segment can contain an extended character set indicator (ECI) or a Structured Append header.

Instances of this class represent such a data segment. They retain the data in the original unencoded form until the bit stream for the QR code is created.

public abstract class DataSegment

Inheritance

object

DataSegment

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Constructors

DataSegment(DataSegmentMode, int)

Creates a new instance with the given data segment mode and encoded data length.

protected DataSegment(DataSegmentMode mode, int encodedLength)

Parameters

mode DataSegmentMode

The data segment mode.

encodedLength int

The length of the encoded data, without mode and count indicator, in bits.

Properties

DataBytes

The data bytes.

public ArraySegment<byte> DataBytes { get; protected set; }

Property Value

ArraySegment<byte>

The data bytes (if any).

DataLength

The data length, in bytes.

public int DataLength { get; }

Property Value

int

The data length, in bytes.

EciDesignator

Gets the extended character set indicator (ECI).

This value is only valid if this segment uses the segment mode ECI.

public virtual ECI EciDesignator { get; }

Property Value

ECI

EncodedLength

The length of the encoded segment, in bits.

The length is without the header (mode indicator and count indicator).

public int EncodedLength { get; }

Property Value

int

Mode

The data segment mode.

public DataSegmentMode Mode { get; }

Property Value

DataSegmentMode

The data segment mode.

StructuredAppendParity

The data parity in the structured append messages.

The value is only valid if this segment uses the segment mode StructuredAppend.

public virtual byte StructuredAppendParity { get; }

Property Value

byte

StructuredAppendPosition

The position of the QR code within a structured append message.

Valid positions are between 1 and 16. The value is only valid if this segment uses the segment mode StructuredAppend.

public virtual int StructuredAppendPosition { get; }

Property Value

int

StructuredAppendTotal

The total number of QR codes used for the structured append message.

Valid numbers are between 1 and 16. The value is only valid if this segment uses the segment mode StructuredAppend.

public virtual int StructuredAppendTotal { get; }

Property Value

int

Methods

FromBinaryData(byte[], ECI, int, bool)

Creates optimal data segments for the specified binary data.

The optimal segments are the segments representing the data with the smallest number of bits. For a given text, they slightly differ depending on the QR code version. If the QR code version is not known, the default value (20) will produce the optimal result except for rare cases.

The specified data can be text data that has already been encoded using a text encoding.

The resulting data segments will refer to the data byte array. It must not be changed until the QR code has been generated.

public static List<DataSegment> FromBinaryData(byte[] data, ECI eci = null, int version = 20, bool considerKanjiMode = false)

Parameters

data byte[]

The binary data to encode.

eci ECI

The extended character set indicator segment to add. If None is specified, the ECI segment if omitted. If null is specified, the ECI designator for binary data is used.

version int

The QR code version.

considerKanjiMode bool

Controls if Kanji mode is considered for data segments.

Returns

List<DataSegment>

A list of QR data segments representing the data.

FromText(string, ECI, Encoding, int, KanjiStrategy)

Creates optimal data segments for the specified text string.

The optimal segments are the segments resulting in the smallest number of bits. For a given text, they slightly differ depending on the QR code version. If the QR code version is not known, the default value (20) will produce the optimal result except for rare cases.

If eci is null or Automatic, then Latin-1 / ISO-8859-1 character encoding is used if the text can be encoded without loss in this encoding. If so, no ECI segment is added. Otherwise, the text is encoded in UTF-8 and an ECI segment is added. The parameter encoding will be ignored.

If eci is None, then no ECI segment is added. The text will be encoded using the specified encoding. The parameter encoding is mandatory in this case.

In all other cases, the specified ECI segment is added. The text is encoded using the specified encoding. If encoding is null, then the encoding is derived from eci.

kanjiStrategy controls if Kanji mode is considered for encoding data segments. For the best compatibility, it should only be used if the text is encoded in Shift-JIS. This is the default behavior.

public static List<DataSegment> FromText(string text, ECI eci = null, Encoding encoding = null, int version = 20, KanjiStrategy kanjiStrategy = KanjiStrategy.Automatic)

Parameters

text string

The text to encode.

eci ECI

The extended character set indicator segment to add.

encoding Encoding

The character set encoding to use, or null if it should be derived from the ECI.

version int

The QR code version.

kanjiStrategy KanjiStrategy

Controls if Kanji mode is used for data segments.

Returns

List<DataSegment>

List of QR data segments representing the text.

Remarks

Most encodings other than Latin-1 / ISO-8859-1 and the UTF encodings require that the encoding is registered (except for .NET Framework 4.x), typically using:

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

GetText(IEnumerable<DataSegment>)

Gets the text encoded in the given sequence of segments.

public static string GetText(IEnumerable<DataSegment> segments)

Parameters

segments IEnumerable<DataSegment>

The segments.

Returns

string

The text.

GetTotalLength(int)

Gets the encoded segment length, in bits.

The length includes the mode indicator, the count indicator, and the data bits. It depends on the QR code version.

public int GetTotalLength(int version)

Parameters

version int

The QR code version.

Returns

int

The segment length, in bits.

MakeECISegment(ECI)

Creates a new ECI data segment.

public static DataSegment MakeECISegment(ECI designator)

Parameters

designator ECI

The ECI designator.

Returns

DataSegment

An ECI data segment.

See Also

ECI

MakeSegment(DataSegmentMode, ArraySegment<byte>)

Creates a new data segment for encoding the specified data.

This method only supports the modes for encoding data: numeric, alphanumeric, Kanji and byte.

public static DataSegment MakeSegment(DataSegmentMode dataSegmentMode, ArraySegment<byte> dataBytes)

Parameters

dataSegmentMode DataSegmentMode

The data segment mode.

dataBytes ArraySegment<byte>

The character or binary data.

Returns

DataSegment

The new data segment.

Exceptions

ArgumentOutOfRangeException

Thrown if an unsupported data segment mode is specified.

ArgumentNullException

Thrown if dataBytes.Array is null.

MakeStructuredAppend(int, int, byte)

Creates a structured append data segment.

public static DataSegment MakeStructuredAppend(int position, int total, byte parity)

Parameters

position int

The position of the QR code within the message (1 to 16).

total int

The total number of QR code used for the message (1 to 16).

parity byte

The message parity.

Returns

DataSegment

A structured append data segment.

Exceptions

ArgumentOutOfRangeException

Thrown if 1 ≤ position ≤ total ≤ 16 is violated.

ToString()

public override string ToString()

Returns

string