adodb.stream

Stream 對象用於表示二進制數據流或文本流。使用Stream對象可以為資料庫應用程式很方便地添加圖像數據。

基本介紹

• 外文名：adodb.stream
• 作用：方便地添加圖像數據
• 對象1：方便地添加圖像數據
• 對象2：表示二進制數據流或文本流

說明

在諸如檔案系統或電子郵件系統這樣的樹狀分級結構中，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 的訪問模式

打開方法

打開 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 也將以唯讀模式打開。

參數列表：

adModeRead =1

adModeReadWrite =3

adModeRecursive =4194304

adModeShareDenyNone =16

adModeShareDenyRead =4

adModeShareDenyWrite =8

adModeShareExclusive =12

adModeUnknown =0

adModeWrite =2

OpenOptions

可選。StreamOpenOptionsEnum 值。默認值為 adOpenStreamUnspecified。

adOpenStreamAsync =1

adOpenStreamFromRecord =4

adOpenStreamUnspecified=-1

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 操作完成為止。

關閉方法

關閉打開的對象和任何相關的對象。

語法

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 值，指定是否在指定字元串的結尾寫入分行符字元。

adWriteChar =0

adWriteLine =1

說明

指定的字元串被寫入 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 覆蓋現有檔案的當前內容。

adSaveCreateNotExist =1

adSaveCreateOverWrite = 2

注意 如果覆蓋現有的檔案（設定 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。