ADODB.Stream 对象详解

ADODB.Stream 对象详解

Stream 对象 表示二进制数据或文本的流。


说明

在诸如文件系统或电子邮件系统这样的树状分级结构中，Record 可能有一个与之相关联的位的默认二进制流，其中包含文件或电子邮件的内容。Stream 对象可用于对包含这些数据流的字段或记录进行操作。可以通过下列方式获取 Stream 对象：

通过指向包含二进制或文本数据的对象（通常是文件）的 URL。此对象可以是简单的文档、表示结构化文档的 Record 对象或文件夹。


通过打开与 Record 对象相关联的默认 Stream 对象。打开 Record 时便可获取与 Record 对象相关联的默认流。只需打开该流便可删除一个往返过程。


通过将 Stream 对象实例化。这些 Stream 对象可用来存储用于应用程序的数据。跟与 URL 相关联的 Stream 或 Record 的默认 Stream 不同，实例化的 Stream 在默认情况下与基本源没有关联。
用 Stream 对象的方法和属性可以执行下列操作：

用 Open 方法从 Record 或 URL 打开 Stream 对象。


用 Close 方法关闭 Stream。


用 Write 和 WriteText 方法向 Stream 中输入字节或文本。


用 Read 和 ReadText 方法从 Stream 中读取字节。


用 Flush 方法将仍在 ADO 缓冲区中的任何 Stream 数据写入基本对象。


用 CopyTo 方法将 Stream 的内容复制到另一 Stream。


用 SkipLine 方法和 LineSeparator 属性控制从源文件中读取行的方式。


用 EOS 属性和 SetEOS 方法确定流位置的结尾。


用 SaveToFile 和 LoadFromFile 方法保存和恢复文件中的数据。


用 Charset 属性指定用于存储 Stream 的字符集。


用 Cancel 方法终止异步 Stream 操作。


用 Size 属性确定 Stream 中的字节数。


用 Position 属性控制 Stream 中的当前位置。


用 Type 属性确定 Stream 中的数据类型。


用 State 属性确定 Stream 的当前状态（已打开、关闭或正在执行）。


用 Mode 属性指定 Stream 的访问模式。

Open 方法 (ADO Stream)


打开 Stream 对象来操作二进制或文本数据的流。

语法

Stream.Open Source, Mode, OpenOptions, UserName, Password

参数

Source 可选。Variant 值，指定 Stream 的数据源。Source 可能包含绝对 URL 字符串，该字符串指向某个众所周知的树状结构（如电子邮件或文件系统）中现有的节点。应使用 URL 关键字（“URL=http://server/folder”）来指定 URL。另外，Source 也可包含对已打开的 Record 对象的引用，该对象打开与 Record 相关联的默认流。如果未指定 Source，Stream 将被实例化并被打开，默认情况下它不与基本源相关联。

Mode 可选。ConnectModeEnum 值，指定得出的 Stream 的访问模式（例如，读/写或只读）。默认值为 adModeUnknown。有关访问模式的详细信息，请参阅 Mode 属性。如果未指定 Mode，它将被源对象继承。例如，如果以只读模式打开源 Record，那么默认情况下 Stream 也将以只读模式打开。

OpenOptions 可选。StreamOpenOptionsEnum 值。默认值为 adOpenStreamUnspecified。

UserName 可选。String 值，包含（在需要时）访问 Stream 对象的用户标识。

Password 可选。String 值，包含（在需要时）访问 Stream 对象的密码。

说明

当把 Record 对象作为源参数传递时，将不使用 UserID 和 Password 参数，因为这样就已经可以访问 Record 对象。与之类似，Record 对象的 Mode 也被传递给 Stream 对象。

如果未指定 Source，打开的 Stream 将不包含数据，并且其 Size 为零 (0)。当 Stream 关闭时，要避免丢失任何写入此 Stream 的数据，请用 CopyTo 或 SaveToFile 方法保存 Stream，或将其保存到另一个内存位置。

Stream 未打开时，有可能读取 Stream 的所有只读属性。如果异步打开 Stream，所有后续的操作（除了检查 State 和其他只读属性）都将被阻塞，直到 Open 操作完成为止。

Close 方法


关闭打开的对象和任何相关的对象。

语法

object.Close

说明

使用 Close 方法关闭 Connection、Record、Recordset 或 Stream 对象以便释放任何相关联的系统资源。关闭对象不会将其从内存中删除；随后可以更改其属性设置并再次将其打开。要从内存中彻底清除对象，请在关闭对象后将对象变量设置为 Nothing（在 Visual Basic 中）。

Connection

使用 Close 方法关闭 Connection 对象还将关闭与连接相关联的任何活动 Recordset 对象。与正在关闭的 Connection 对象相关联的 Command 对象将被持久保留，但不再与 Connection 对象相关联，即其 ActiveConnection 属性将被设置为 Nothing。还将从 Command 对象的 Parameters 集合中清除任何提供者定义的参数。

随后可以调用 Open 方法重新建立与相同数据源或其他数据源的连接。在 Connection 对象关闭后，调用任何需要与数据源打开连接的方法都将产生错误。

当连接上的 Recordset 对象打开时，关闭 Connection 对象将回卷所有 Recordset 对象中的挂起更改。在事务进行过程中显式关闭 Connection 对象（调用 Close 方法）将产生错误。如果在事务进行过程中 Connection 对象超出范围，ADO 将自动回卷事务。

Recordset、Record 和 Stream

使用 Close 方法关闭 Recordset、Record 或 Stream 对象将释放相关联的数据和可能通过此特定对象对数据进行的独立访问。随后可以调用 Open 方法重新打开具有相同属性或修改属性的对象。

在 Recordset 对象关闭后，调用任何需要活动游标的方法都将产生错误。

如果在立即更新模式下进行编辑，调用 Close 方法将产生错误，应先调用 Update 或 CancelUpdate 方法。如果在批更新模式下关闭 Recordset 对象，自上次 UpdateBatch 调用以来所做的更改将全部丢失。

如果使用 Clone 方法创建打开的 Recordset 对象的副本，关闭原 Recordset 或其副本不会影响任何其他副本。

Write 方法


将二进制数据写入 Stream 对象。

语法

Stream.Write Buffer

参数

Buffer Variant，包含要写入的字节数组。

说明

指定的字节被写入 Stream 对象，每个字节之间没有间隔。

当前 Position 被设置为写入数据的后一个字节。Write 方法不会截断流中剩余的数据。如果要截断这些字节，请调用 SetEOS。

如果写入超过了当前 EOS 位置，Stream 的 Size 将增加以包含新的字节，EOS 也将移动到 Stream 中新的最后一个字节。

WriteText 方法


将指定的文本字符串写入 Stream 对象。

语法

Stream.WriteText Data, Options

参数

Data String 值，包含要写入的字符文本。

Options 可选。StreamWriteEnum 值，指定是否在指定字符串的结尾写入分行符字符。

说明

指定的字符串被写入 Stream 对象，每个字符串之间没有间隔空格或字符。

当前 Position 被设置为写入数据的后一个字节。WriteText 方法不会截断流中剩余的数据。如果要截断这些字节，请调用 SetEOS。

如果写入超过了当前 EOS 位置，Stream 的 Size 将增加以包含新的字符，EOS 也将移动到 Stream 中新的最后一个字节。
Read 方法


从二进制 Stream 对象读取指定的字节数。

语法

Variant = Stream.Read ( NumBytes )

参数

NumBytes 可选。Long 值，指定要从文件或 StreamReadEnum 值 adReadAll（默认值）读取的字节数。

返回值

Read 方法从 Stream 对象读取指定的字节数或整个流，并以 Variant 形式返回所得到的数据。

说明

如果 NumBytes 超过 Stream 中剩余的字节数，将只返回剩余的字节。数据读取没有被填充到与 NumBytes 指定的长度一致。如果没有剩余的字节可读取，将返回一个值为 Null 的变体。Read 不能用于向后读取。

注意 NumBytes 始终度量字节。对于文本 Stream 对象，请使用 ReadText。

ReadText 方法


从文本 Stream 对象读取指定数目的字符。

语法

String = Stream.ReadText ( NumChars )

参数

NumChars 可选。Long 值，指定要从文件读取的字符数，或 StreamReadEnum 值。默认值为 adReadAll。

返回值

ReadText 方法从 Stream 对象中读取指定数目的字符、整个行或整个流，并返回所得到的字符串。

说明

如果 NumChar 超过流中剩余的字符数，将只返回剩余的字符。读取的字符串没有被填充到与 NumChar 指定的长度一致。如果没有剩余的字符可读取，将返回一个值为 Null 的变体。ReadText 不能用于向后读取。

ReadText 方法与文本流（Type 为 adTypeText）一起使用。对于二进制流，请使用 Read。

Flush 方法


将保留在 ADO 缓冲区中的 Stream 的内容强加到与 Stream 相关联的基本对象。

语法

Stream.Flush

说明

此方法可用于将流缓冲区的内容发送到 URL（Stream 对象源）表示的基本对象。要确保对 Stream 内容所做的所有更改都被写入，应调用此方法。但是使用 ADO 时一般不必调用 Flush，因为 ADO 尽可能在后台不断刷新其缓冲区。Stream 内容的更改将自动进行，在调用 Flush 前不会被缓存。

用 Close 方法关闭 Stream 将自动刷新 Stream 的内容，而无需在 Close 之前显式地调用 Flush。


CopyTo 方法


将 Stream 中指定数目的字符或字节（取决于 Type）复制到另一个 Stream 对象。

语法

Stream.CopyTo DestStream, NumChars

参数

DestStream 对象变量值，包含打开的 Stream 对象的引用。将当前 Stream 复制到由 DestStream 指定的目标 Stream。目标 Stream 必须已打开。否则，将发生运行时错误。

注意 DestStream 参数可能不会成为 Stream 对象的代理，因为这将需要访问 Stream 对象上无法与客户远程连接的专用接口。

NumChars 可选。Integer 值，指定要从源 Stream 中的当前位置复制到目标 Stream 的字节或字符数目。默认值为 –1，它指定将所有字符或字节从当前位置复制到 EOS。

说明

此方法从 Position 属性指定的当前位置开始，复制指定数目的字符或字节。如果指定的数目超过可用的数目（即超过 EOS），那么只复制当前位置到 EOS 之间的字符或字节。如果省略 NumChars 值或其值为 –1，将复制从当前位置开始的所有字符或字节。

如果在目标流中存在现有字符或字节，超过复制结束位置的所有内容将保留，不会被截断。Position 成为紧跟在复制的最后一个字节后面的字节。如果要截断这些字节，请调用 SetEOS。

应使用 CopyTo 将数据复制到与源 Stream 同类型的目标 Stream（两者的 Type 属性设置都是 adTypeText，或者都是 adTypeBinary）。对于文本 Stream 对象，可以更改目标 Stream 的 Charset 属性设置以进行字符集间的转换。还可以将文本 Stream 对象成功地复制到二进制 Stream 对象中，但却不能将二进制 Stream 对象复制到文本 Stream 对象中。

SkipLine 方法


读取文本流时跳过一整行。

语法

Stream.SkipLine

说明

到（包括）下一个分行符之间的所有字符都被跳过。默认情况下，LineSeparator 为 adCRLF。如果试图跳过超出 EOS 的位置，那么当前位置将保持在 EOS 处。

SkipLine 方法与文本流（Type 为 adTypeText）一起使用。

LineSeparator 属性


指示要在文本 Stream 对象中用作分行符的二进制字符。

设置和返回值

设置或返回 LineSeparatorsEnum 值，指示用在 Stream 中的分行符。默认值为 adCRLF。

说明

读取文本 Stream 的内容时，LineSeparator 用于解释行。可以用 SkipLine 方法跳过行。

LineSeparator 只能与文本 Stream 对象（Type 为 adTypeText）一起使用。如果 Type 为 adTypeBinary，则忽略此属性。

EOS 属性


指示当前位置是否在流的结尾处。

返回值

返回 Boolean 值，指示当前位置是否在流的结尾处。如果流中没有其他字节，则 EOS 返回 True；如果当前位置后还有其他字节，则返回 False。

若要设置流的结尾位置，请使用 SetEOS 方法。若要确定当前位置，请使用 Position 属性。

SetEOS 方法


设置流的结尾位置。

语法

Stream.SetEOS

说明

SetEOS 通过使当前 Position 成为流的结尾来更新 EOS 属性的值。当前位置后面的所有字节或字符都将被截断。

由于 Write、WriteText 和 CopyTo 不截断现有 Stream 对象中多余的值，因此可以通过用 SetEOS 设置新的流结尾位置来截断这些字节或字符。

警告 如果将 EOS 设置到流的实际结尾前面的位置，那么新的 EOS 位置后面的所有数据都将丢失。

SaveToFile 方法


把 Stream 的二进制内容保存到文件。

语法

Stream.SaveToFile FileName, SaveOptions

参数

FileName String 值，包含要保存 Stream 内容的文件的完整名称。可以保存到任何有效的本地位置，或任何可以通过 UNC 值访问的位置。

SaveOptions SaveOptionsEnum 值，指定当文件不存在时 SaveToFile 是否创建新文件。默认值为 adSaveCreateNotExists。如果指定的文件不存在，可以用这些选项来指定产生错误。还可以指定 SaveToFile 覆盖现有文件的当前内容。

注意 如果覆盖现有的文件（设置 adSaveCreateOverwrite），SaveToFile 将截断原始文件中超出新 EOS 的所有字节。

说明

SaveToFile 可用于将 Stream 对象的内容复制到本地文件。Stream 对象的内容或属性不发生变化。调用 SaveToFile 之前，Stream 对象必须被打开。

此方法不更改 Stream 对象与其基本源的关联。Stream 对象将仍与原来的 URL 关联，该 URL 在 Stream 对象打开时就是其源。

完成 SaveToFile 操作后，流中的当前位置 (Position) 被设置到流的开始处 (0)。

LoadFromFile 方法


将现有文件的内容加载到 Stream 中。

语法

Stream.LoadFromFile FileName

参数

FileName String 值，包含要加载到 Stream 中的文件的名称。FileName 可以包含任何 UNC 格式的有效路径和名称。如果指定的文件不存在，将发生运行时错误。

说明

此方法可用于将本地文件的内容加载到 Stream 对象中。还可用于将本地文件的内容上载至服务器。

调用 LoadFromFile 之前 Stream 对象必须是打开的。此方法不改变 Stream 对象的绑定；它将仍旧绑定到原来打开 Stream 的 URL 所指定的对象。LoadFromFile 用从该文件中读取的数据覆盖 Stream 对象的当前内容。

Stream 中任何现有的字节都被该文件的内容覆盖。LoadFromFile 创建的 EOS 后跟随的任何原有和剩余的字节都将被截去。

在调用 LoadFromFile 后，当前位置将设置在 Stream 的开始处（Position 为 0）。

Charset 属性


指示用于转换文本 Stream 内容的字符集。

设置和返回值

设置或返回 String 值，该值指定用于转换 String 内容的字符集。默认值为“Unicode”。所允许的值是作为 Internet 字符集字符串（例如，“iso-8859-1”，“Windows-1252”等）被传递到接口的典型字符串。有关系统支持的字符集字符串的列表，请参阅 Windows 注册表中 HKEY_CLASSES_ROOT\MIME\Database\Charset 的子键。

说明

在文本 Stream 对象中，文本对象存储为 Unicode。Charset 属性将用指定的字符集转换从 Stream 读取的数据。与之类似，以指定字符集写入 Stream 的数据被转换为 Unicode 以便存储在 Stream 对象中。

对于打开的 Stream，其当前 Position 须位于 Stream (0) 的开始处，这样才能设置 Charset。

Charset 只能与文本 Stream 对象（Type 为 adTypeText）一起使用。如果 Type 为 adTypeBinary，则忽略此属性。

Size 属性 (ADO Stream)


指示流的字节数。

返回值

返回 Long 值，指定流的字节数。默认值为流的大小，如果不知道流的大小，则该值为 -1。

说明

Size 只能与打开的 Stream 对象配合使用。

注意 Stream 对象中可以存储任意多个位，它仅受系统资源限制。如果 Stream 包含的位数超过 Long 值所能表示的位数，Size 将被截断因而不能精确表示 Stream 的长度。

Position 属性


指示在 Stream 对象中的当前位置。

设置和返回值

设置或返回 Long 值，指定流开始处到当前位置的偏移字节数。默认值为 0，表示流中的第一个字节。

说明

可将当前位置移动到流的结尾处后面的一点。如果在流结尾处以外的地方指定当前位置，Stream 对象的 Size 也将随之增加。所有以这种方式添加的新字节都将为 Null。

注意 Position 始终度量字节。对于使用多字节字符集的文本流，请将位置与字符大小相乘以确定字符数。例如，对于双字节字符集，第一个字符位置为 0，第二个字符位置为 2，第三个字符位置为 4，依此类推。

不能用负值更改 Stream 中的当前位置。只有正数才能用于 Position。

对于只读 Stream 对象，如果设置的 Position 值超过 Stream 的 Size，ADO 将不返回错误。这不会更改 Stream 的大小，也不会以任何方式改变 Stream 的内容。但是，应避免这种操作，因为它可能产生无意义 Position 值。

Type 属性 (ADO Stream)


指示 Stream 中包含的数据的类型（二进制或文本）。

设置和返回值

设置或返回 StreamTypeEnum 值，用于指定包含在 Stream 对象中的数据类型。默认值为 adTypeText。但如果二进制数据最初被写入新的空 Stream 中，Type 将被更改为 adTypeBinary。

说明

只有在当前位置位于 Stream 的开始处（Position 为 0）时，Type 属性才为读/写；位于其他位置时均为只读。

State 属性


对所有适用的对象，指示该对象状态是打开的还是关闭的。

指示对所有可应用的对象执行异步方法，指示对象的当前状态是正在连接、正在执行还是正在检索。

返回值

返回可能是 ObjectStateEnum 值的 Long 值。默认值为 adStateClosed。

说明

可以随时用 State 属性确定给定对象的当前状态。

对象的 State 属性可以是值的组合。例如，如果正在执行某个语句，此属性将有一个 adStateOpen 和 adStateExecuting 的组合值。

State 属性为只读。

Mode 属性


指示在 Connection、Record 或 Stream 对象中修改数据的有效权限。

设置和返回值

设置或返回 ConnectModeEnum 值。对于 Connection，默认值为 adModeUnknown。对于 Record 对象，默认值为 adModeRead。对于与基本源相关联的 Stream（用 URL 将其作为源打开或者作为 Record 的默认 Stream 打开），默认值为 adReadOnly。对于与基本源不关联的 Stream（在内存中实例化），默认值为 adModeUnknown。

说明

使用 Mode 属性设置或返回当前连接上提供者使用的访问权限。只有当 Connection 对象关闭时，才能设置 Mode 属性。

对于 Stream 对象，如果未指定访问模式，它将从用于打开 Stream 对象的源继承。例如，如果 Stream 是从 Record 对象打开的，默认情况下它将以打开 Record 对象相同的模式打开。

此属性在对象关闭时为读/写，在对象打开时为只读。

远程数据服务用法 当在客户端的 Connection 对象上使用时，Mode 属性只能设置为 adModeUnknown。

原文：http://hi.baidu.com/tension_zy/blog/item/dbf235ca19db3b4ff21fe778.html