ADODB.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 對象相同的模式打開。

此屬性在對象關閉時為讀/寫，在對象打開時為隻讀。