IFileParameter

Beschreibung:

IFileParameter repräsentiert sowohl einen Eingangs-, als auch einen Ausgangs-Parameter eines Jobs, der eine Datei enthält.

import "OxSvrSpt.idl"

Die IFileParameter -Schnittstelle stellt Methoden für den Zugriff auf den FileParameter und die zugrunde liegende Datei zur Verfügung.

Für den Zugriff auf die Datei stehen ähnlich der IParameter -Schnittstelle sowohl Stream-, Chunk-, sowie XML-Funktionalitäten zur Verfügung.

Solange keine der Datei-Zugriffsfunktionalitäten aufgerufen werden, wird die Datei nicht geöffnet. Beim ersten Zugriff auf eine Methode, die mit der Datei arbeitet, wird diese im modeReadWrite | shareDenyNone -Modus geöffnet. Über UnloadStream ist es möglich, diese ausdrücklich wieder zu schleißen, um für den Zugriff durch andere Prozesse einen exklusiven Zugriff zu ermöglichen.

Öffentliche Methoden:

HRESULT Stream ([out, retval] IStream ** ppStream)
HRESULT AppendChung ([in]VARIANT Data)
HRESULT GetChunk ([in] long Length, [out, retval] VARIANT * pResult)
HRESULT ResetStream ()
HRESULT ClearStream ()
HRESULT UnloadStream ([in, defaultvalue(-1)] VAIRANT_BOOL AutoReload)

Properties:

BSTR FileName [get, set]
long ActualSize [get]
BSTR XML [get, set]
VARIANT_BOOL AutoDelete [get, set]

Dokumentation der Elementfunktionen:

  • HRESULT AppendChung ([in]VARIANT Data)

AppendChunk hängt zusätzliche Bytes an den Stream an.

Beim ersten Zugriff auf eine der Streamfunktionalitäten der Schnittstelle wird die zugrundeliegende Datei geöffnet und offen gehalten. Wird von einem anderen Aufrufer anschließend ein exklusiver Zugriff auf diese Datei benötigt, kann sie über den Aufruf der Methode UnloadStream wieder freigegeben werden.

Nach dem Aufruf dieser Methode steht der Positionszeiger des internen Streams auf dessen Ende.

Parameter:

[in]: Data enthält die Daten, die an den Stream angehängt werden sollen.

Die Daten werden über die OLE32 ChangeType -Methode nach VT_ARRAY|VT_UI1 konvertiert und weiterverarbeitet. Wird z. B. ein BSTR übergeben, werden die Daten als WIDECHAR weiterverarbeitet. Das Schreiben von 8bit-Zeichen in den Stream kann über die Methoden des Helper-COM -Objektes erfolgen.

Beispiel:

Dim abWriteData() As Byte
ReDim abWriteData(0 To 5)
abWriteData(0) = 0
abWriteData(1) = 1
abWriteData(2) = 2
abWriteData(3) = 3
abWriteData(4) = 4
abWriteData(5) = 5
oFileParameter.AppendChunk abWriteData

  • HRESULT ClearStream ()

ClearStream löscht die Daten des Streams und der zugrunde liegendenden Datei.

  • HRESULT GetChunk ([in] long Length, [out, retval] VARIANT * pResult)

GetChunk liefert die angegebene Anzahl von Bytes aus dem Stream zurück.

Beim ersten Zugriff auf eine der Streamfunktionalitäten der Schnittstelle wird die zugrundeliegende Datei geöffnet und offen gehalten. Wird von einem anderen Aufrufer anschließend ein exklusiver Zugriff auf diese Datei benötigt, kann sie uber den Aufruf der Methode UnloadStream wieder freigegeben werden.

Diese Methode beginnt ab der aktuellen Position im Stream die Daten zu lesen. Wird das Ende des Streams erreicht, bevor die gewünschte Anzahl an Zeichen gelesen wurde, werden nur die bis dahin gelesenen Zeichen zurückgeliefert. Die Anzahl der gelesenen Zeichen kann anhand der Größe des zurückgelieferten Puffers bestimmt werden (siehe Beispiel).

Parameter:

[in]: Length Anzahl der maximal zurückgeliefertten Bytes.

[out]: pResult (VB-Rückgabeparameter) enthält die gelesenen Bytes. Diese werden in einem Variant vom Typ VT_ARRAY|VT_UI1 geliefert.

Beispiel:

' der folgende Programm-Ausschnitt entspricht:
' Dim var
' var = oFileParameter.Value
' dort bleibt jedoch zusätzlich die aktuelle Position des Streams erhalten
' Stream zum Lesen auf die Anfangsposition setzen
oFileParameter.ResetStream
Dim abReadData() As Byte
...
' Array auf die benötigte Größe anpassen
ReDim abReadData(0 To oParameter.ActualSize - 1)
' Daten lesen
abReadData = oFileParameter.GetChunk(oParameter.ActualSize)
' Größe der gelesenen Daten anhand der zurückgegebenen Daten ermitteln
Dim nSize As Long
nSize = UBound(abReadData) - LBound(abReadData)

  • HRESULT ResetStream ()

ResetStream setzt den Datenstream auf den Anfang zurück.

Beim ersten Zugriff auf eine der Streamfunktionalitäten der Schnittstelle wird die zugrundeliegende Datei geöffnet und offen gehalten. Wird von einem anderen Aufrufer anschließend ein exklusiver Zugriff auf diese Datei benötigt, kann sie uber den Aufruf der Methode UnloadStream wieder freigegeben werden.

  • HRESULT Stream ([out, retval] IStream ** ppStream)

Stream liefert den Stream der Binärdaten

Der Stream enthält die Binärdaten der Datei.

Beim ersten Zugriff auf eine der Streamfunktionalitäten der Schnittstelle wird die zugrundeliegende Datei geöffnet und offen gehalten. Wird von einem anderen Aufrufer anschließend ein exklusiver Zugriff auf diese Datei benötigt, kann sie uber den Aufruf der Methode UnloadStream wieder freigegeben werden.

Parameter:

[out]: ppStream (VB-Rückgabeparameter) enthält den Stream als IStream -Schnittstelle.

  • HRESULT UnloadStream ([in, defaultvalue(-1)] VAIRANT_BOOL AutoReload)

UnloadStream entläd das interne Stream -Objekt

Wenn keine externen Referenzen mehr auf das Stream -Objekt verweisen, wird dieses freigegeben und die zugrundeliegende Datei geschlossen. Bei einem erneuten Zgriff über eine Methode, die das Streamobjekt verwendet wird dieser erneut aufgebaut.

Hinweis:

Ist AutoDelete auf true gestellt und wird der Stream entladen, wird wenn keine andere Referenz auf den Stream mehr besteht, die zugrunde liegende Datei gelöscht.

Parameter:

[in]: AutoReload gibt an, ob beim nächsten Zugriff auf eine Methode von IFileParameter, die den Stream benötigt, dieser wieder automatisch neu initialisiert wird. Vor allem bei der Verwendung von Debug-Umgebungen, die automatisch die betreffenden Eigenschaften neu laden, kann es zu Problemen führen, wenn die Datei exklusiv durch andere Programme weiterverarbeit werden soll. In diesem Fall sollte der Wert VARIANT_FALSE für diesen Parameter verwendet werden. In Sprachen, die Standardparameter unterstützen wird dieser Wert beim Nichtangeben auf VARIANT_TRUE gesetzt.

Dokumentation der Properties:

  • long ActualSize [get]

ActualSize liefert die Größe des Datenstreams in Byte zurück.

Beim ersten Zugriff auf eine der Streamfunktionalitäten der Schnittstelle wird die zugrundeliegende Datei geöffnet und offen gehalten. Wird von einem anderen Aufrufer anschließend ein exklusiver Zugriff auf diese Datei benötigt, kann sie uber den Aufruf der Methode UnloadStream wieder freigegeben werden.

Parameter:

[out]: pVal (VB-Rückgabeparameter) enthält die Größe des Datenstreams.

  • VARIANT_BOOL AutoDelete [get, set]

AutoDelete liefert, ob die Datei von diesem Objekt nach dem Gebrauch automatisch gelöscht werden soll und setzt, ob die Datei von diesem Objekt nach dem Gebrauch automatisch gelöscht werden soll.

Die Kontrolle über das automatische Löschen der Datei erfolgt im zugrundeliegenden FileStream. Es besteht daher die Möglichkeit, mit dem Stream auch nach der Zerstörung des FileParameter -Objektes weiterzuarbeiten. Wenn keine der Streamfunktionalitäten verwendet wurde, überprüft der FileParameter im Release, ob die Datei zu löschen ist.

Parameter:

[out]: pVal (VB-Rückgabeparameter) soll die Datei automatisch gelöscht werden?

Die Kontrolle über das automatische Löschen der Datei erfolgt im zugrunde liegenden File-Stream. Es besteht daher die Möglichkeit, mit dem Stream auch nach der Zerstörung des FileParameter -Objektes weiterzuarbeiten. Wenn keine der Streamfunktionalitäten verwendet wurde, überprüft der FileParameter im Release, ob die Datei zu löschen ist.

Parameter:

[in]: newVal soll die Datei automatisch gelöscht werden?

  • BSTR FileName [get, set]

FileName liefert den vollständigen Namen der Datei zurück und setzt einen neuen Dateinamen.

Diese Eigenschaft ist die Standardeingenschaft der Schnittstelle

Parameter:

[out]: pVal (VB-Rückgabeparameter) Name der Datei

Wird bereits mit einer Datei gearbeitet, werden deren Resourcen freigegeben. Schlägt die Zuweisung eines neuen Dateinamens fehl (die Datei wird nicht gefunden) wird ein Fehler gemeldet und das Objekt behält die alten Einstellungen.

Parameter:

[in]: newVal neuer Dateiname

  • BSTR XML [get, set]

XML liefert den Inhalt des File-Parameters als XML-String und schreibt die übergebene XMLZeichenkette, in die zugrunde liegende Datei.

Beim ersten Zugriff auf eine der Streamfunktionalitäten der Schnittstelle wird die zugrunde liegende Datei geöffnet und offen gehalten. Wird von einem anderen Aufrufer anschließend ein exklusiver Zugriff auf diese Datei benötigt, kann sie uber den Aufruf der Methode UnloadStream wieder freigegeben werden.

Die ausgegebene XML-Zeichenkette wird über den XML-Parsers ausgelesen.

Lässt sich aus den Daten keine valide XML-Zeichenkette generieren, wird ein Fehler geworfen. Die Fehlermeldung richtet sich nach dem zur Validierung verwendeten XML-Parsers (MSXML4).

Der Positionszeiger des Streams wird durch den Aufruf dieser Eigenschaft nicht verändert.

Parameter:

[out]: pVal (VB-Rückgabeparameter) enthält die als XML-Zeichenkette dekodierten Daten.

Die alten Daten der Datei werden durch den Aufruf dieser Eigenschaft überschrieben. Nach dem Aufruf dieser Eigenschaft weist der Positionszeiger des Streams auf den Anfang desselben.

Die Daten werden entsprechend der in der XML-Zeichenkette angegebenen Kodierung in die Datei geschrieben.

Die übergebenen Daten werden bei der Konvertierung validiert. Werden nicht-XML-konforme Daten übergeben, wird ein Fehler ausgelöst. Der Stream hat in diesem Fall die Länge 0. Die Fehlermeldung richtet sich nach dem zur Validierung verwendeten XML-Parser (MS-XML4).

Parameter:

[in]: newVal Basicstring mit den XML-Daten.