Export (0) Print
Expand All

DecoderFallbackBuffer Class

Updated: October 2010

Provides a buffer that allows a fallback handler to return an alternate string to a decoder when it cannot decode an input byte sequence.

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)

public abstract class DecoderFallbackBuffer

An encoding defines a mapping between a Unicode character and an encoded sequence of bytes. A decoding operation, which converts an input byte sequence to an output character, fails if no mapping is defined for a particular byte sequence.

The .NET Framework provides a failure handling mechanism, called a fallback, if a conversion cannot be performed. All decoder fallback handlers must implement the following:

  • A decoder fallback, which is represented by a class derived from the DecoderFallback class.

  • A decoder fallback buffer, which is represented by a type derived from the DecoderFallbackBuffer class that can return a string to the conversion operation.

Fallbacks can use three strategies to handle conversion failures:

  • Best-fit mapping. The decoder fallback buffer can return a string that represents a close approximation to the input byte sequence. The .NET Framework does not provide a public best-fit DecoderFallbackBuffer implementation.

  • Replacement. The decoder fallback buffer can return a string, such as a question mark ("?"), that indicates that a byte sequence could not be decoded. In the .NET Framework, the DecoderReplacementFallback and DecoderReplacementFallbackBuffer classes provide a public replacement fallback buffer implementation. The constructor of the DecoderReplacementFallback class enables you to define the replacement string.

  • Exception. The DecoderFallbackBuffer implementation throws an exception, which indicates that a byte sequence cannot be decoded, and terminates the decoding operation. In this case, the fallback handler must provide a DecoderFallbackBuffer implementation, although it does not return a string to the decoder. In the .NET Framework, the DecoderExceptionFallback and DecoderExceptionFallbackBuffer classes provide a public exception fallback implementation that throws a DecoderFallbackException when a byte sequence cannot be decoded.

The buffer in a DecoderFallbackBuffer implementation represents the entire string to be returned to the decoder in response to a decoder fallback. Generally, implementations also include state information, such as the index of the next character to return to the decoder and the number of remaining characters to be returned. Because DecoderFallbackBuffer is an abstract class, it requires derived classes to implement the following members at a minimum:

  • The Fallback method, which is called by the decoder when it cannot decode a byte sequence. The decoder passes two pieces of information to the fallback buffer implementation: an array containing the bytes that could not be decoded and the index of the first byte in the input byte array. In a decoder fallback exception handler, the exception is thrown in this method. Otherwise, the method returns true if it provides a fallback, or false if it does not.

  • The GetNextChar method, which is called repeatedly by the decoder if the Fallback method returns true. In successive calls, the handler should return each character in its buffer. When it has returned all characters, it should return U+0000. An exception fallback handler always returns U+0000.

  • The MovePrevious method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns false.

  • The Remaining property, which indicates the number of remaining characters to be returned to the decoder. An exception fallback handler always returns zero.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0

Date

History

Reason

October 2010

Revised extensively.

Information enhancement.

Community Additions

ADD
Show:
© 2014 Microsoft