IFileParameter

Description:

IFileParameter represents both an input and output parameter of a Job that contains a file.

import "OxSvrSpt.idl"

The IFileParameter interface provides methods for accessing the FileParameter and the underlying file.

For accessing the file, similar to the IParameter interface, stream, chunk, and XML functionalities are available.

As long as none of the file access functionalities are called, the file is not opened. When first accessing a method that works with the file, it is opened in modeReadWrite | shareDenyNone mode. Through UnloadStream it is possible to explicitly close it again to enable exclusive access for other processes.

Public Methods:

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]

Documentation of Element Functions:

  • HRESULT AppendChung ([in]VARIANT Data)

AppendChunk appends additional bytes to the stream.

When first accessing any of the stream functionalities of the interface, the underlying file is opened and kept open. If another caller subsequently needs exclusive access to this file, it can be released again by calling the UnloadStream method.

After calling this method, the position pointer of the internal stream is positioned at its end.

Parameters:

[in]: Data contains the data to be appended to the stream.

The data are converted to VT_ARRAY|VT_UI1 via the OLE32 ChangeType method and further processed. For example, if a BSTR is passed, the data are processed as WIDECHAR. Writing 8-bit characters to the stream can be done via methods of the Helper-COM object.

Example:

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 deletes the data of the stream and the underlying file.

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

GetChunk returns the specified number of bytes from the stream.

When first accessing any of the stream functionalities of the interface, the underlying file is opened and kept open. If another caller subsequently needs exclusive access to this file, it can be released again by calling the UnloadStream method.

This method begins reading data from the current position in the stream. If the end of the stream is reached before the desired number of characters is read, only the characters read up to that point are returned. The number of characters read can be determined by the size of the returned buffer (see example).

Parameters:

[in]: Length number of bytes to be returned at most.

[out]: pResult (VB return parameter) contains the read bytes. These are returned as a Variant of type VT_ARRAY|VT_UI1.

Example:

' The following program excerpt is equivalent to:
' Dim var
' var = oFileParameter.Value
' however, the current stream position is preserved
' Set stream to beginning position for reading
oFileParameter.ResetStream
Dim abReadData() As Byte
...
' Adjust array to required size
ReDim abReadData(0 To oParameter.ActualSize - 1)
' Read data
abReadData = oFileParameter.GetChunk(oParameter.ActualSize)
' Determine size of read data based on returned data
Dim nSize As Long
nSize = UBound(abReadData) - LBound(abReadData)

  • HRESULT ResetStream ()

ResetStream resets the data stream to the beginning.

When first accessing any of the stream functionalities of the interface, the underlying file is opened and kept open. If another caller subsequently needs exclusive access to this file, it can be released again by calling the UnloadStream method.

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

Stream returns the stream of binary data.

The stream contains the binary data of the file.

When first accessing any of the stream functionalities of the interface, the underlying file is opened and kept open. If another caller subsequently needs exclusive access to this file, it can be released again by calling the UnloadStream method.

Parameters:

[out]: ppStream (VB return parameter) contains the stream as an IStream interface.

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

UnloadStream unloads the internal Stream object.

When no external references point to the Stream object anymore, it is released and the underlying file is closed. When accessing it again through a method that uses the stream object, it is rebuilt again.

Note:

If AutoDelete is set to true and the Stream is unloaded, when no other reference to the stream exists, the underlying file is deleted.

Parameters:

[in]: AutoReload indicates whether when accessing a method of IFileParameter that requires the Stream again, it is automatically reinitialized. Especially in debugging environments that automatically reload the relevant properties, problems can arise when the file should be exclusively processed by other programs. In this case, the value VARIANT_FALSE should be used for this parameter. In languages that support default parameters, this value is set to VARIANT_TRUE when not specified.

Documentation of Properties:

  • long ActualSize [get]

ActualSize returns the size of the data stream in bytes.

When first accessing any of the stream functionalities of the interface, the underlying file is opened and kept open. If another caller subsequently needs exclusive access to this file, it can be released again by calling the UnloadStream method.

Parameters:

[out]: pVal (VB return parameter) contains the size of the data stream.

  • VARIANT_BOOL AutoDelete [get, set]

AutoDelete returns whether the file should be automatically deleted by this object after use and sets whether the file should be automatically deleted by this object after use.

Control over automatic deletion of the file is performed in the underlying FileStream. Therefore, it is possible to continue working with the Stream even after destruction of the FileParameter object. If none of the stream functionalities have been used, the FileParameter checks in Release whether the file should be deleted.

Parameters:

[out]: pVal (VB return parameter) should the file be automatically deleted?

Control over automatic deletion of the file is performed in the underlying FileStream. Therefore, it is possible to continue working with the Stream even after destruction of the FileParameter object. If none of the stream functionalities have been used, the FileParameter checks in Release whether the file should be deleted.

Parameters:

[in]: newVal should the file be automatically deleted?

  • BSTR FileName [get, set]

FileName returns the complete name of the file and sets a new filename.

This property is the default property of the interface.

Parameters:

[out]: pVal (VB return parameter) name of the file

If working with a file already, its resources are released. If assigning a new filename fails (the file is not found), an error is reported and the object retains the old settings.

Parameters:

[in]: newVal new filename

  • BSTR XML [get, set]

XML returns the content of the file parameter as an XML string and writes the passed XML string to the underlying file.

When first accessing any of the stream functionalities of the interface, the underlying file is opened and kept open. If another caller subsequently needs exclusive access to this file, it can be released again by calling the UnloadStream method.

The output XML string is read via the XML parser.

If a valid XML string cannot be generated from the data, an error is thrown. The error message depends on the XML parser used for validation (MSXML4).

The position pointer of the Stream is not changed by calling this property.

Parameters:

[out]: pVal (VB return parameter) contains the data decoded as XML string.

The old data of the file are overwritten by calling this property. After calling this property, the position pointer of the Stream points to the beginning of the stream.

The data are written to the file according to the encoding specified in the XML string.

The passed data are validated during conversion. If non-XML-conformant data are passed, an error is raised. In this case, the Stream has length 0. The error message depends on the XML parser used for validation (MS-XML4).

Parameters:

[in]: newVal basic string with XML data.