1<?xml version="1.0" encoding="utf-8"?>
2<Type Name="DecoderFallbackBuffer" FullName="System.Text.DecoderFallbackBuffer">
3  <TypeSignature Language="C#" Value="public abstract class DecoderFallbackBuffer" />
4  <TypeSignature Language="ILAsm" Value=".class public auto ansi abstract beforefieldinit DecoderFallbackBuffer extends System.Object" />
5  <AssemblyInfo>
6    <AssemblyName>mscorlib</AssemblyName>
7    <AssemblyVersion>2.0.0.0</AssemblyVersion>
8    <AssemblyVersion>4.0.0.0</AssemblyVersion>
9  </AssemblyInfo>
10  <Base>
11    <BaseTypeName>System.Object</BaseTypeName>
12  </Base>
13  <Interfaces />
14  <Docs>
15    <since version=".NET 2.0" />
16    <remarks>
17      <attribution license="cc4" from="Microsoft" modified="false" />
18      <para>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. </para>
19      <para>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: </para>
20      <list type="bullet">
21        <item>
22          <para>A decoder fallback, which is represented by a class derived from the <see cref="T:System.Text.DecoderFallback" /> class.</para>
23        </item>
24        <item>
25          <para>A decoder fallback buffer, which is represented by a type derived from the <see cref="T:System.Text.DecoderFallbackBuffer" /> class that can return a string to the conversion operation.</para>
26        </item>
27      </list>
28      <para>Fallbacks can use three strategies to handle conversion failures: </para>
29      <list type="bullet">
30        <item>
31          <para>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 <see cref="T:System.Text.DecoderFallbackBuffer" /> implementation.</para>
32        </item>
33        <item>
34          <para>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 <see cref="T:System.Text.DecoderReplacementFallback" /> and <see cref="T:System.Text.DecoderReplacementFallbackBuffer" /> classes provide a public replacement fallback buffer implementation. The constructor of the <see cref="T:System.Text.DecoderReplacementFallback" /> class enables you to define the replacement string.</para>
35        </item>
36        <item>
37          <para>Exception. The <see cref="T:System.Text.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 <see cref="T:System.Text.DecoderFallbackBuffer" /> implementation, although it does not return a string to the decoder. In the .NET Framework, the <see cref="T:System.Text.DecoderExceptionFallback" /> and <see cref="T:System.Text.DecoderExceptionFallbackBuffer" /> classes provide a public exception fallback implementation that throws a <see cref="T:System.Text.DecoderFallbackException" /> when a byte sequence cannot be decoded.</para>
38        </item>
39      </list>
40      <para>The buffer in a <see cref="T:System.Text.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 <see cref="T:System.Text.DecoderFallbackBuffer" /> is an abstract class, it requires derived classes to implement the following members at a minimum:</para>
41      <list type="bullet">
42        <item>
43          <para>The <see cref="M:System.Text.DecoderFallbackBuffer.Fallback(System.Byte[],System.Int32)" /> 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.</para>
44        </item>
45        <item>
46          <para>The <see cref="M:System.Text.DecoderFallbackBuffer.GetNextChar" /> method, which is called repeatedly by the decoder if the <see cref="M:System.Text.DecoderFallbackBuffer.Fallback(System.Byte[],System.Int32)" /> 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.</para>
47        </item>
48        <item>
49          <para>The <see cref="M:System.Text.DecoderFallbackBuffer.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.</para>
50        </item>
51        <item>
52          <para>The <see cref="P:System.Text.DecoderFallbackBuffer.Remaining" /> property, which indicates the number of remaining characters to be returned to the decoder. An exception fallback handler always returns zero.</para>
53        </item>
54      </list>
55    </remarks>
56    <summary>
57      <attribution license="cc4" from="Microsoft" modified="false" />
58      <para>Provides a buffer that allows a fallback handler to return an alternate string to a decoder when it cannot decode an input byte sequence. </para>
59    </summary>
60  </Docs>
61  <Members>
62    <Member MemberName=".ctor">
63      <MemberSignature Language="C#" Value="protected DecoderFallbackBuffer ();" />
64      <MemberSignature Language="ILAsm" Value=".method familyhidebysig specialname rtspecialname instance void .ctor() cil managed" />
65      <MemberType>Constructor</MemberType>
66      <AssemblyInfo>
67        <AssemblyVersion>2.0.0.0</AssemblyVersion>
68        <AssemblyVersion>4.0.0.0</AssemblyVersion>
69      </AssemblyInfo>
70      <Parameters />
71      <Docs>
72        <remarks>To be added.</remarks>
73        <since version=".NET 2.0" />
74        <summary>
75          <attribution license="cc4" from="Microsoft" modified="false" />
76          <para>Initializes a new instance of the <see cref="T:System.Text.DecoderFallbackBuffer" /> class. </para>
77        </summary>
78      </Docs>
79    </Member>
80    <Member MemberName="Fallback">
81      <MemberSignature Language="C#" Value="public abstract bool Fallback (byte[] bytesUnknown, int index);" />
82      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance bool Fallback(unsigned int8[] bytesUnknown, int32 index) cil managed" />
83      <MemberType>Method</MemberType>
84      <AssemblyInfo>
85        <AssemblyVersion>2.0.0.0</AssemblyVersion>
86        <AssemblyVersion>4.0.0.0</AssemblyVersion>
87      </AssemblyInfo>
88      <ReturnValue>
89        <ReturnType>System.Boolean</ReturnType>
90      </ReturnValue>
91      <Parameters>
92        <Parameter Name="bytesUnknown" Type="System.Byte[]" />
93        <Parameter Name="index" Type="System.Int32" />
94      </Parameters>
95      <Docs>
96        <since version=".NET 2.0" />
97        <remarks>
98          <attribution license="cc4" from="Microsoft" modified="false" />
99          <para>The <see cref="M:System.Text.Encoding.GetChars(System.Byte[])" />, <see cref="M:System.Text.Encoding.GetString(System.Byte[])" />, and <see cref="Overload:System.Text.Decoder.Convert" /> methods call <see cref="M:System.Text.DecoderFallbackBuffer.Fallback(System.Byte[],System.Int32)" /> if they encounter an unknown input byte sequence that cannot be decoded. A return value of true indicates that the fallback buffer can process the input byte sequence, which causes the calling method to call the <see cref="M:System.Text.DecoderFallbackBuffer.GetNextChar" /> method to obtain each character of the fallback buffer. Because it does not process individual bytes, the <see cref="M:System.Text.DecoderFallbackBuffer.Fallback(System.Byte[],System.Int32)" /> method in an exception fallback handler throws an exception.</para>
100        </remarks>
101        <summary>
102          <attribution license="cc4" from="Microsoft" modified="false" />
103          <para>When overridden in a derived class, prepares the fallback buffer to handle the specified input byte sequence.</para>
104        </summary>
105        <returns>
106          <attribution license="cc4" from="Microsoft" modified="false" />
107          <para>true if the fallback buffer can process <paramref name="bytesUnknown" />; false if the fallback buffer ignores <paramref name="bytesUnknown" />.</para>
108        </returns>
109        <param name="bytesUnknown">
110          <attribution license="cc4" from="Microsoft" modified="false" />An input array of bytes.</param>
111        <param name="index">
112          <attribution license="cc4" from="Microsoft" modified="false" />The index position of a byte in <paramref name="bytesUnknown" />.</param>
113      </Docs>
114    </Member>
115    <Member MemberName="GetNextChar">
116      <MemberSignature Language="C#" Value="public abstract char GetNextChar ();" />
117      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance char GetNextChar() cil managed" />
118      <MemberType>Method</MemberType>
119      <AssemblyInfo>
120        <AssemblyVersion>2.0.0.0</AssemblyVersion>
121        <AssemblyVersion>4.0.0.0</AssemblyVersion>
122      </AssemblyInfo>
123      <ReturnValue>
124        <ReturnType>System.Char</ReturnType>
125      </ReturnValue>
126      <Parameters />
127      <Docs>
128        <since version=".NET 2.0" />
129        <remarks>
130          <attribution license="cc4" from="Microsoft" modified="false" />
131          <para>A decoding operation calls the <see cref="M:System.Text.DecoderFallbackBuffer.Fallback(System.Byte[],System.Int32)" /> method if the operation encounters an unknown byte sequence in the input. If the <see cref="M:System.Text.DecoderFallbackBuffer.Fallback(System.Byte[],System.Int32)" /> method returns true, a substitute string exists that can be inserted in the output instead of decoding the unknown input. The decoding operation calls the <see cref="M:System.Text.DecoderFallbackBuffer.GetNextChar" /> method repeatedly and obtains the substitute string one character at a time. When all characters in the fallback buffer have been returned to the decoder, the method should return U+0000.</para>
132          <para>For an exception fallback handler, the <see cref="M:System.Text.DecoderFallbackBuffer.GetNextChar" /> method should return U+0000. </para>
133        </remarks>
134        <summary>
135          <attribution license="cc4" from="Microsoft" modified="false" />
136          <para>When overridden in a derived class, retrieves the next character in the fallback buffer.</para>
137        </summary>
138        <returns>
139          <attribution license="cc4" from="Microsoft" modified="false" />
140          <para>The next character in the fallback buffer.</para>
141        </returns>
142      </Docs>
143    </Member>
144    <Member MemberName="MovePrevious">
145      <MemberSignature Language="C#" Value="public abstract bool MovePrevious ();" />
146      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance bool MovePrevious() cil managed" />
147      <MemberType>Method</MemberType>
148      <AssemblyInfo>
149        <AssemblyVersion>2.0.0.0</AssemblyVersion>
150        <AssemblyVersion>4.0.0.0</AssemblyVersion>
151      </AssemblyInfo>
152      <ReturnValue>
153        <ReturnType>System.Boolean</ReturnType>
154      </ReturnValue>
155      <Parameters />
156      <Docs>
157        <since version=".NET 2.0" />
158        <remarks>
159          <attribution license="cc4" from="Microsoft" modified="false" />
160          <para>An exception fallback handler should return false.</para>
161        </remarks>
162        <summary>
163          <attribution license="cc4" from="Microsoft" modified="false" />
164          <para>When overridden in a derived class, causes the next call to the <see cref="M:System.Text.DecoderFallbackBuffer.GetNextChar" /> method to access the data buffer character position that is prior to the current character position. </para>
165        </summary>
166        <returns>
167          <attribution license="cc4" from="Microsoft" modified="false" />
168          <para>true if the <see cref="M:System.Text.DecoderFallbackBuffer.MovePrevious" /> operation was successful; otherwise, false.</para>
169        </returns>
170      </Docs>
171    </Member>
172    <Member MemberName="Remaining">
173      <MemberSignature Language="C#" Value="public abstract int Remaining { get; }" />
174      <MemberSignature Language="ILAsm" Value=".property instance int32 Remaining" />
175      <MemberType>Property</MemberType>
176      <AssemblyInfo>
177        <AssemblyVersion>2.0.0.0</AssemblyVersion>
178        <AssemblyVersion>4.0.0.0</AssemblyVersion>
179      </AssemblyInfo>
180      <ReturnValue>
181        <ReturnType>System.Int32</ReturnType>
182      </ReturnValue>
183      <Docs>
184        <value>To be added.</value>
185        <since version=".NET 2.0" />
186        <remarks>
187          <attribution license="cc4" from="Microsoft" modified="false" />
188          <para>The <see cref="M:System.Text.DecoderFallbackBuffer.Fallback(System.Byte[],System.Int32)" /> method returns true if <see cref="P:System.Text.DecoderFallbackBuffer.Remaining" /> is a nonzero value.</para>
189          <para>For an exception fallback handler, the <see cref="P:System.Text.DecoderFallbackBuffer.Remaining" /> method should return zero.</para>
190        </remarks>
191        <summary>
192          <attribution license="cc4" from="Microsoft" modified="false" />
193          <para>When overridden in a derived class, gets the number of characters in the current <see cref="T:System.Text.DecoderFallbackBuffer" /> object that remain to be processed.</para>
194        </summary>
195      </Docs>
196    </Member>
197    <Member MemberName="Reset">
198      <MemberSignature Language="C#" Value="public virtual void Reset ();" />
199      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Reset() cil managed" />
200      <MemberType>Method</MemberType>
201      <AssemblyInfo>
202        <AssemblyVersion>2.0.0.0</AssemblyVersion>
203        <AssemblyVersion>4.0.0.0</AssemblyVersion>
204      </AssemblyInfo>
205      <ReturnValue>
206        <ReturnType>System.Void</ReturnType>
207      </ReturnValue>
208      <Parameters />
209      <Docs>
210        <remarks>To be added.</remarks>
211        <since version=".NET 2.0" />
212        <summary>
213          <attribution license="cc4" from="Microsoft" modified="false" />
214          <para>Initializes all data and state information pertaining to this fallback buffer.</para>
215        </summary>
216      </Docs>
217    </Member>
218  </Members>
219</Type>