# IFileParameter Description: `IFileParameter` represents both an input and output parameter of a `Job` that contains a file. ```cpp 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: ```cpp HRESULT Stream ([out, retval] IStream ** ppStream) HRESULT AppendChung ([in]VARIANT Data) HRESULT GetChunk ([in] long Length, [out, retval] VARIANT * pResult) ``` ```cpp HRESULT ResetStream () HRESULT ClearStream () HRESULT UnloadStream ([in, defaultvalue(-1)] VAIRANT_BOOL AutoReload) ``` Properties: ```cpp 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: : `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: ```vb 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: : `Length` number of bytes to be returned at most. : `pResult` (VB return parameter) contains the read bytes. These are returned as a Variant of type VT_ARRAY|VT_UI1. Example: ```vb ' 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: : `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: : `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: : `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: : `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: : `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: : `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: : `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: : `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: : `newVal` basic string with XML data.