5 Redirected IO

5.1 Using Redirected IO

A developer can redirect the IO for an input or output file by providing a data structure that contains pointers to custom IO routines for reading and writing. This data structure is passed in place of a typical file specification. The developer must set the dwSpecType parameter of the file to IOTYPE_REDIRECT when the file is sent. When dwSpecType is set this way, the pSpec element must contain a pointer to a developer-defined data structure that begins with a BASEIO structure (defined in baseIO.H). The BASEIO structure contains pointers to the basic IO functions for the file's IO system such as Read, Seek, Tell, and so forth. The developer must initialize these function pointers to their own functions that perform IO tasks. Beyond the BASEIO element, the developer may place any data. For instance, a developer's structure might look like the following:

typedef struct MYFILEtag
{
   BASEIO    sBaseIO;       /* must be the first element */
   VTDWORD   dwMyInfo1;
   VTDWORD   dwMyInfo2;
   .
   .
   .
} MYFILE;

Because the pSpec passed is essentially the "file handle" that uses, the developer can redirect the IO on a file-by-file basis while still "regular" disk-based files.

The BASEIO structure is defined as follows:

typedef struct BASEIOtag
{
    IOCLOSEPROC pClose;
    IOREADPROC pRead;
    IOWRITEPROC pWrite;
    IOSEEKPROC pSeek;
    IOTELLPROC pTell;
    IOGETINFOPROC pGetInfo;
    IOOPENPROC pOpen; /* pOpen *MUST* be set to NULL. */
#ifndef NLM
    IOSEEK64PROC pSeek64;
    IOTELL64PROC pTell64;
#endif
    VTVOID *aDummy[3];
} BASEIO, * PBASEIO;

The developer must implement the Close, Read, Seek, Tell and GetInfo routines. The Open routine must be set to NULL. The first parameter to each of these routines is called hFile and is of the type HIOFILE. HIOFILE is simply the VTLPVOID to your data structure that was passed in the pSpec parameter of the Outside IN API call.

5.2 IOClose

Closes the file identified by hFile and cleans up all memory associated with the file.

Prototype

IOERR IOClose(
   HIOFILE   hFile);

Parameters

• hFile: Identifies the file to be closed. Should be cast into a pointer to your data structure (MYFILE in the preceding discussion).

Return Values

• IOERR_OK: Close was successful.

• IOERR_UNKNOWN: Some error occurred on close.

5.3 IORead

Reads data from the current file position forward and resets the position to the byte after the last byte read.

Prototype

IOERR IORead(
   HIOFILE         hFile,
   VTBYTE       *  pData,
   VTDWORD         dwSize,
   VTDWORD      * pCount);

Parameters

• hFile: Identifies the file to be read. Should be cast into a pointer to your data structure (MYFILE in the preceding discussion).

• pData: Points to the buffer into which the bytes should be read. Will be at least dwSize bytes big.

• dwSize: Number of bytes to read.

• pCount: Points to the number of bytes actually read by the function. This value is only valid if the return value is IOERR_OK.

Return Values

• IOERR_OK: Read was successful. pCount contains the number of bytes read and pData contains the bytes themselves.

• IOERR_EOF: Read failed because the file pointer was beyond the end of the file at the time of the read.

• IOERR_UNKNOWN: Read failed for some other reason.

5.4 IOWrite

Writes data from the current file position forward and resets the position to the byte after the last byte written.

Prototype

IOERR IOWrite(
   HIOFILE         hFile,
   VTBYTE       *  pData,
   VTDWORD         dwSize,
   VTDWORD      * pCount);

Parameters

• hFile: Identifies the file where the data is to be written. Should be cast into a pointer to your data structure (MYFILE in the preceding discussion).

• pData: Points to the buffer from which the bytes should be written. It must be at least dwSize bytes big.

• dwSize: Number of bytes to write.

• pCount: Points to the number of bytes actually written by the function. This value is only valid if the return value is IOERR_OK.

Return Values

• IOERR_OK: Write was successful, pCount contains the number of bytes written.

• IOERR_UNKNOWN: Write failed for some reason.

5.5 IOSeek

Moves the current file position.

Prototype

IOERR IOSeek(
   HIOFILE   hFile,
   VTWORD    wFrom,
   VTLONG    lOffset);

Parameters

• hFile: Identifies the file to be read. Should be cast into a pointer to your data structure (MYFILE in the preceding discussion).

• wFrom: One of the following values:

  • IOSEEK_TOP: Move the file position lOffset bytes from the top (beginning) of the file.

  • IOSEEK_BOTTOM: Move the file position lOffset bytes from the bottom (end) of the file.

  • IOSEEK_CURRENT: Move the file position lOffset bytes from the current file position.

• lOffset: Number of bytes to move the file pointer. A positive value moves the file pointer forward in the file and a negative value moves it backward. If a requested seek value would move the file pointer before the beginning of the file, the file pointer should remain unchanged and IOERR_UNKNOWN should be returned. Seeking past EOF is allowed. In that case IOERR_OK should be returned. IOTell would return the requested seek position and IORead should return IOERR_EOF and 0 bytes read.

Return Values

• IOERR_OK: Seek was successful.

• IOERR_UNKNOWN: Seek failed for some reason.

5.6 IOTell

Returns the current file position.

Prototype

IOERR IOTell(
   HIOFILE         hFile,
   VTDWORD       * pOffset);

Parameters

• hFile: Identifies the file to be read. Should be cast into a pointer to your data structure (MYFILE in the preceding discussion).

• pOffset: Points to the current file position returned by the function.

Return Values

• IOERR_OK: Tell was successful.

• IOERR_UNKNOWN: Tell failed for some reason.

5.7 IOGetInfo

Returns information about an open file.

Prototype

IOERR IOGetInfo(
   HIOFILE        hFile,
   VTDWORD        dwInfoId,
   VTVOID       * pInfo);

Parameters

• hFile: Identifies the file to be read. Should be cast into a pointer to your data structure (MYFILE in the previous discussion).

• dwInfoId: One of the following values:

  • IOGETINFO_FILENAME: pInfo points to a string that should be filled with the base file name (no path) of the open file (for example TEST.DOC). If you do not know the file name, return IOERR_UNKNOWN. Certain file types (such as DataEase) must know the original file name in order to open secondary files required to correctly view the original file. If you return IOERR_UNKNOWN, these file types do not convert.

  • IOGETINFO_PATHNAME: pInfo points to a string that should be filled with the fully qualified path name (including the file name) of the open file. For example, C:\MYDIR\TEST.DOC. If you do not know the path name, return IOERR_UNKNOWN.

  • IOGETINFO_PATHTYPE: pInfo points to a DWORD that should be filled with the IOTYPE of the path returned by IOGETINFO_PATHNAME. For instance, if you return a DOS path name in the Unicode character set, you should return IOTYPE_UNICODEPATH.

  • IOGETINFO_ISOLE2STORAGE: Must return IOERR_FALSE. pInfo is not used.

  • IOGETINFO_GENSECONDARY: pInfo points to a structure of type IOGENSECONDARY. Some file types require supporting files to be opened. These supporting files may contain formatting information or extra data. Correct handling of IOGETINFO_GENSECONDARY is critical to the operation of the Outside In technology.

    Because the developer is in total control of the IO for the primary file, the technology does not know how to generate a path to these secondary files or even if the secondary files are accessible through the regular file system. The IOGETINFO_GENSECONDARY call gives the developer a chance to resolve this problem by generating a new IO specification for the secondary file in question. The developer gets just the base file name (often embedded in the original document or generated from the primary file's name) of the secondary file.

    The developer may either use one of the standard Outside In IO types or totally redirect the IO for the secondary file, as well.

  • IOGETINFO_64BITIO: For redirected I/O that wishes to use 64-bit seek/tell functions, your IOGetInfo function must respond IOERR_TRUE to this dwInfoId. In addition, the pSeek64/pTell64 items in the baseio structure must be valid pointers to the proper function types.

  Any other value should return IOERR_BADINFOID.

• pInfo: The size of the pInfo buffer depends on the dwInfoId selected. For IOGETINFO_FILENAME and IOGETINFO_PATHNAME, the buffer is of size MAX_PATH characters (each character is either one byte or two, depending on PATHTYPE). The IOGETINFO_PATHTYPE buffer is the size of a VTDWORD.

Return Values

• IOERR_OK: GetInfo was successful.

• IOERR_TRUE: Affirmative response from a true or false GetInfo.

• IOERR_FALSE: Negative response from a true or false GetInfo.

• IOERR_BADINFOID: dwInfoId can not be handled by this file type.

• IOERR_INVALIDSPEC: The file spec is bad for this type.

• IOERR_UNKNOWN: GetInfo failed for some other reason.

typedef struct
{
   VTDWORD     dwSize;
   VTLPBYTE    pFileName;
   VTDWORD     dwSpecType;
   VTLPVOID    pSpec;
   VTDWORD     dwOpenFlags
} IOGENSECONDARY, * PIOGENSECONDARY;


typedef struct
{
   VTDWORD     dwSize;
   VTLPWORD    pFileName;
   VTDWORD     dwSpecType;
   VTLPVOID    pSpec;
   VTDWORD     dwOpenFlags
} IOGENSECONDARYW, * PIOGENSECONDARYW;

5.8 IOSEEK64PROC / IOTELL64PROC

These functions are for seek/tell using 64-bit offsets. These functions are not used by default. Rather, they are used if the IOGETINFO_64BITIO message returns IOERR_TRUE. This is so redirected I/O using strictly 32-bit I/O is unaffected.

IOERR IOSeek64(
HIOFILE hFile,
VTWORD wFrom,
VTOFF_T offset);

IOERR IOTell64(
HIOFILE hFile,
VTOFF_T * pOffset);