/*
* STOR.H
*
* Header file for ArchiveLib 2.0
*
* Copyright (c) 1994-1996 Greenleaf Software, Inc.
* All Rights Reserved
*
* DESCRIPTION
*
* This file contains the class declaration for the very important
* base class ALStorage.
*
* CLASS DEFINITIONS:
*
* ALStorage
*
* REVISION HISTORY
*
* May 26, 1994 1.0A : First release
*
* August 10, 1994 1.0B : Added some copyright info.
*
* January 1, 1995 1.01A : Renamed this file to prevent a clash with
* STORAGE.H used by compiler vendors for
* OLE implementation. :(
*
* February 14, 1996 2.0A : New release
*/
#ifndef _STOR_H
#define _STOR_H
#include <stddef.h> /* need for size_t */
#include "timedate.h"
#include "fileattr.h"
#if defined( __cplusplus )
/*
* class ALStorage
*
* DESCRIPTION
*
* ALStorage is a base class that defines the different types
* of storage objects used by Archive Library. The two most
* commonly used storage object types are file objects and memory
* objects, defined by the derived classes ALFile and
* ALMemory.
*
* ALStorage objects are used to store and retrieve objects from archives.
* They are also used to store and retrieve the archives themselves,
* allowing archives to be stored in files or directly in memory.
*
* The ALStorage adds buffering to the storage object, allowing for
* fast access to data presently cached in memory. This is very similar to
* the buffering provided for FILE types in stdio.h. Note that this
* buffering is generally only efficient/useful if lots of sequential
* reads or writes are being done, as opposed to random accessess.
*
* ALStorage objects give up a lot of flexibility in order to provide
* quick and efficient access to data. The primary way this affects
* use of the class is that the I/O buffer can only be used for reading
* or writing, but not both simultaneously. The class doesn't check
* for this at run time, so programmers need to enforce it themselves.
*
* When a read is initiated for the first time, the buffer is loaded up,
* and subsequent reads are performed out of the I/O buffer. To switch
* to writing mode, a call to FlushBuffer needs to be performed, which
* will reset the input and output indices. Likewise, when, done writing,
* a call to FlushBuffer() can be performed to clear the indices. A
* read can be done subsequently.
*
* DATA MEMBERS
*
* mpcBuffer : This is the I/O buffer. I read big blocks of
* data into this buffer, then I can perform
* character reads from an inline function that
* doesn't have to access any virtual fns. Speeds
* things up tremendously. Likewise, I write
* to this buffer using inline functions until it
* it is full. Only then do I call a virtual
* to flush it to disk, memory, or whatever.
*
* muBufferValidData : This keeps track of the end of valid data,
* both when reading and writing. When you
* read in a block of data, this index is set
* to the end of the data. When writing, this
* index is continually updated to reflect the
* end of the user written data.
*
* muWriteIndex : The index in the I/O buffer where the next byte
* is going to be written.
*
* muReadIndex : The index in the I/O buffer where the next read
* will come from.
*
* mlFilePointer : The current location of the read/write pointer
* in the underlying object, e.g. a file. This
* is the location where the data will be written
* out of the I/O buffer when a FlushBuffer() call
* is made. Or, if reading, it is where the next
* LoadBuffer() will read data from.
*
* mlSize : The size of the file/object. This will ordinarily
* be set to -1 when we create an object, because
* we don't know the size yet. When you call Open()
* for an existing object, the value will usually
* be loaded using some sort of system call. We
* also can figure out what the size is when we do
* a ReadDirectory call on an archive.
*
* mlCrc32 : The CRC-32 for the object. This value normally
* won't be known until an object has been placed
* in an archive, or when the information has
* been read out using in ReadDirectory().
*
* miUpdateCrcFlag : This flag is set to indicate that we are in the
* process of calculating the CRC while the file
* is being compressed.
*
* miCreated : This flag will be set if the file was opened
* using Create(), clear if it was opened using
* Open(). When miCreated is set, we will try
* to set the file time, date and attributes when
* we close the file. This is so we can set these
* attributes when we are recreating a file that
* was stored in an archive.
*
* miStorageObjectType : An integer that is assigned when the object was
* constructed. Usually one of the enumerated
* constants found in ALDEFS.H. This is the number
* that gets stored in the Archive directory with
* the object, so we can figure out what type of
* object to create when extracting.
*
* muBufferSize : The size of the I/O buffer.
*
* mpMonitor : A pointer to the monitor attached to this object.
* During the archiving process, this pointer gets
* set by the archive routine for each storage object
* as it is being processes. A value of 0 just
* means no monitor is watching this object at the
* moment.
*
* mTimeDate : The time and date stamp for the file, this usually
* gets set when the object is opened using Open(),
* it is also set when we read in a storage object's
* information using ReadDirectory().
*
* mAttributes : The attributes associated with the file. R/H/S/A/D.
*
* mName : The name of the storage object.
*
* mStatus : The current status of the object.
*
* MEMBER FUNCTIONS
*
* ALStorage() : The constructor, creates the object, but doesn't
* necessarily create the file/whatever.
* operator=() : Assignment operator.
* operator new() : The memory allocation operator. This is only
* used if the library is in a DLL.
* ~ALStorage() : Virtual destructor.
* UpdateCrc() : Protected function used internally when the
* crc is being calculated
* WriteStorageObjectData() : Protected function to write custom data needed
* for a particular derived classe.
* ReadStorageObjectData() : Protected function read that data back in.
* ReadChar() : Superfast inline function to read a bytee
* WriteChar() : Fast inline function to write a byte.
* ReadBuffer() : Function to read blocks of data.
* WriteBuffer() : Function to write blocks of data.
* Open() : Open() used to prepare an existing object for I/O.
* Create() : Create a new underlying object for I/O.
* Close() : Called when I/O is complete.
* LoadBuffer() : Called to reload the I/O buffer, used internally
* when ReadChar() runs out of stuff to read.
* FlushBuffer() : Called to flush the I/O buffer to the underlying
* object. Called when WriteChar() has gone too far.
* Seek() : Called to reposition the I/O pointer of the
* underlying object.
* YieldTime() : Called whenever a FlushBuffer() or LoadBuffer()
* takes place. Used to update the Monitor attached
* to the file, and to yield time to the O/S.
* Compare() : Compare two storage objects.
* InitCrc32() : Called to start calculating the CRC for an object.
* WriteGlShort() : Write 16 bit integer in little endian format.
* WritePkShort() : Write 16 bit integer in big endian format.
* WriteGlLong() : Write 32 bit integer in little endian format.
* WritePkLong() : Write 32 bit integer in big endian format.
* ReadGlShort() : Read 16 bit integer in little endian format.
* ReadPkShort() : Read 16 bit integer in big endian format.
* ReadGlLong() : Read 32 bit integer in little endian format.
* ReadPkLong() : Read 32 bit integer in big endian format.
* ReadString() : Read a string in ArchiveLib's proprietary format.
* WriteString() : Write string in ArchiveLib format.
* Rename() : Rename the underlying object.
* UnRename() : Undo a rename operation.
* RenameToBackup() : Rename to a special backup name.
* Delete() : Delete an underlying storage object.
* GetCrc32() : Return value of the CRC member.
* GetSize() : Reeturn value of the size member.
* IsOpen() : Indicate if the file is open.
* Tell() : Indicate where the next read or write will
* take place.
* ReadCopyright() : A function to get at the Greenleaf Copyright.
* Clone() : A function used to make a copy of an ALStorage
* object.
* ClearError() : A helper function that clears the error from
* the mStatus member.
*
* REVISION HISTORY
*
* May 26, 1994 1.0A : First release
*
* February 14, 1996 2.0A : New release
*/
/*
* Forward declaration
*/
class AL_CLASS_TYPE ALEntry;
class AL_CLASS_TYPE ALMonitor;
struct AL_CLASS_TYPE ALZipDir;
class AL_CLASS_TYPE ALStorage { /* Tag public class */
public :
/*
* Classes I trust
*/
friend class AL_CLASS_TYPE ALArchive;
friend class AL_CLASS_TYPE ALPkArchive;
friend class AL_CLASS_TYPE ALGlArchive;
friend class AL_CLASS_TYPE ALCompressedObject;
friend class AL_CLASS_TYPE ALPkCompressor;
friend class AL_CLASS_TYPE ALPkDecompressor;
friend void AL_FUNCTION _UpdateEntry( ALEntry AL_DLL_FAR * entry,
ALZipDir AL_DLL_FAR * z );
/*
* Constructors, destructors, assignment operator
*/
protected :
AL_PROTO ALStorage( const char AL_DLL_FAR *file_name,
size_t buffer_size,
const ALStorageType storage_type,
ALCase name_case = AL_MIXED );
ALStorage AL_DLL_FAR & AL_PROTO operator=( const ALStorage AL_DLL_FAR & );
#if defined( AL_USING_DLL ) || defined( AL_BUILDING_DLL )
void AL_DLL_FAR * AL_PROTO operator new( size_t size );
#endif
public :
virtual AL_PROTO ~ALStorage();
/*
* I don't want to allow the copy constructor to exist.
*/
protected :
AL_PROTO ALStorage( const ALStorage AL_DLL_FAR & );
/*
* Member functions, grouped somewhat
*
*
* Private member manipulation
*/
protected :
void AL_PROTO UpdateCrc( size_t count );
/*
* This is private, because it allocates memory in the DLL, so it
* must be deleted in the DLL as well.
*/
protected :
virtual int AL_PROTO
WriteStorageObjectData( ALStorage AL_DLL_FAR * archive );
virtual int AL_PROTO
ReadStorageObjectData( ALStorage AL_DLL_FAR * archive );
/*
* The file I/O access public interface
*/
public :
int AL_PROTO ReadChar();
int AL_PROTO WriteChar( int c );
size_t AL_PROTO ReadBuffer( unsigned char AL_DLL_FAR *buffer,
size_t length );
/* Please keep this arg const, breaks WriteString o/w */
size_t AL_PROTO WriteBuffer( const unsigned char AL_DLL_FAR *buffer,
size_t length );
virtual int AL_PROTO Open();
virtual int AL_PROTO Create( long desired_size = -1L );
virtual int AL_PROTO Close();
virtual int AL_PROTO LoadBuffer( long address ) = 0;
virtual int AL_PROTO FlushBuffer() = 0;
virtual int AL_PROTO Seek( long address ) = 0;
virtual void AL_PROTO YieldTime();
int AL_PROTO Compare( ALStorage AL_DLL_FAR &test_object );
void AL_PROTO InitCrc32( unsigned long seed = 0xffffffffl );
int AL_PROTO WriteGlShort( short int short_data );
int AL_PROTO WritePkShort( short int short_data );
int AL_PROTO WriteGlLong( long long_data );
int AL_PROTO WritePkLong( long long_data );
int AL_PROTO ReadGlShort( short int AL_DLL_FAR &short_data );
int AL_PROTO ReadPkShort( short int AL_DLL_FAR &short_data );
int AL_PROTO ReadGlLong( long AL_DLL_FAR &long_data );
int AL_PROTO ReadPkLong( long AL_DLL_FAR &long_data );
int AL_PROTO ReadString( ALName AL_DLL_FAR &name, short int length = -1 );
int AL_PROTO WriteString( const char AL_DLL_FAR *string_data );
/*
* File manipulation public interface
*/
public :
virtual int AL_PROTO Rename( const char AL_DLL_FAR *new_name = 0,
int delete_on_clash = 1 ) = 0;
virtual int AL_PROTO UnRename( int delete_on_clash = 1 ) = 0;
virtual int AL_PROTO RenameToBackup( int delete_on_clash = 1 ) = 0;
virtual int AL_PROTO Delete() = 0;
/*
* Access functions
*/
public :
long AL_PROTO GetCrc32();
long AL_PROTO GetSize() const;
int AL_PROTO IsOpen();
long AL_PROTO Tell();
static char AL_DLL_FAR * AL_PROTO ReadCopyright();
virtual ALStorage AL_DLL_FAR * AL_PROTO Clone( const char AL_DLL_FAR *name,
int object_type ) const = 0;
void AL_PROTO ClearError();
/*
* Data members
*/
protected :
unsigned char AL_DLL_FAR *mpcBuffer;
size_t muBufferValidData;
size_t muWriteIndex;
size_t muReadIndex;
long mlFilePointer;
long mlSize;
long mlCrc32;
short int miUpdateCrcFlag;
short int miCreated;
/*
* Public members
*/
public :
const ALStorageType miStorageObjectType;
const size_t muBufferSize;
ALMonitor AL_DLL_FAR *mpMonitor;
ALTimeDate mTimeDate;
ALFileAttributes mAttributes;
ALName mName;
ALStatus mStatus;
AL_CLASS_TAG( _ALStorageTag );
};
#include "stor.inl"
#else /* #if defined( __cplusplus ) ... */
AL_LINKAGE long AL_FUNCTION ALStorageGetSize( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageIsOpen( hALStorage this_object );
AL_LINKAGE void AL_FUNCTION ALStorageClearError( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageReadChar( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageWriteChar( hALStorage this_object, int c );
AL_LINKAGE void AL_FUNCTION deleteALStorage( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageOpen( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION
ALStorageCreate( hALStorage this_object, long desired_size );
AL_LINKAGE int AL_FUNCTION ALStorageClose( hALStorage this_object );
AL_LINKAGE size_t AL_FUNCTION
ALStorageReadBuffer( hALStorage this_object,
unsigned char AL_DLL_FAR *buffer,
size_t length );
AL_LINKAGE size_t AL_FUNCTION
ALStorageWriteBuffer( hALStorage this_object,
unsigned char AL_DLL_FAR *buffer,
size_t length );
AL_LINKAGE int AL_FUNCTION
ALStorageWriteString( hALStorage this_object,
char AL_DLL_FAR *string );
AL_LINKAGE long AL_FUNCTION ALStorageTell( hALStorage this_object );
AL_LINKAGE char AL_DLL_FAR * AL_FUNCTION ALReadCopyright( void );
AL_LINKAGE int AL_FUNCTION
ALStorageCompare( hALStorage this_object, hALStorage test_object );
AL_LINKAGE long AL_FUNCTION ALStorageGetCrc32( hALStorage this_object );
AL_LINKAGE void AL_FUNCTION
ALStorageInitCrc32( hALStorage this_object, long seed );
AL_LINKAGE int AL_FUNCTION
ALStorageReadPkLong( hALStorage this_object, long AL_DLL_FAR *long_data );
AL_LINKAGE int AL_FUNCTION
ALStorageReadPkShort( hALStorage this_object, short AL_DLL_FAR *short_data );
AL_LINKAGE int AL_FUNCTION
ALStorageWritePkLong( hALStorage this_object, long long_data );
AL_LINKAGE int AL_FUNCTION
ALStorageWritePkShort( hALStorage this_object, short short_data );
AL_LINKAGE int AL_FUNCTION
ALStorageReadGlShort( hALStorage this_object, short int AL_DLL_FAR *short_data );
AL_LINKAGE int AL_FUNCTION
ALStorageReadGlLong( hALStorage this_object, long int AL_DLL_FAR *long_data );
AL_LINKAGE int AL_FUNCTION
ALStorageWriteGlLong( hALStorage this_object, long long_data );
AL_LINKAGE int AL_FUNCTION
ALStorageWriteGlShort( hALStorage this_object, short short_data );
AL_LINKAGE void AL_FUNCTION ALStorageSetMonitor( hALStorage this_object,
hALMonitor monitor );
AL_LINKAGE int AL_FUNCTION ALStorageDelete( hALStorage this_object );
AL_LINKAGE void AL_FUNCTION ALStorageSetName( hALStorage this_object,
char AL_DLL_FAR *object_name );
AL_LINKAGE int AL_FUNCTION
ALStorageWildCardMatch( hALStorage this_object,
char AL_DLL_FAR *pattern );
AL_LINKAGE char AL_DLL_FAR * AL_FUNCTION
ALStorageChangeExtension( hALStorage this_object,
char AL_DLL_FAR *new_extension );
AL_LINKAGE char AL_DLL_FAR * AL_FUNCTION
ALStorageChangeTrailingChar( hALStorage this_object, char new_char );
AL_LINKAGE char AL_DLL_FAR * AL_FUNCTION
ALStorageGetName( hALStorage this_object );
AL_LINKAGE char AL_DLL_FAR * AL_FUNCTION
ALStorageGetOldName( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION
ALStorageGetStatusCode( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageSetError( hALStorage this_object,
int error,
char AL_DLL_FAR *text );
AL_LINKAGE char AL_DLL_FAR * AL_FUNCTION
ALStorageGetStatusString( hALStorage this_object );
AL_LINKAGE char AL_DLL_FAR * AL_FUNCTION
ALStorageGetStatusDetail( hALStorage this_object );
AL_LINKAGE long AL_FUNCTION ALStorageGetUnixTime( hALStorage this_object );
AL_LINKAGE long AL_FUNCTION ALStorageToJulian( hALStorage this_object );
AL_LINKAGE void AL_FUNCTION
ALStorageFromJulian( hALStorage this_object, long jdn );
AL_LINKAGE void AL_FUNCTION
ALStorageSetTimeDateFromStruc( hALStorage this_object,
struct tm AL_DLL_FAR * time_struct );
AL_LINKAGE void AL_FUNCTION
ALStorageGetStrucFromTimeDate( hALStorage this_object,
struct tm AL_DLL_FAR *time_struct );
AL_LINKAGE void AL_FUNCTION
ALStorageSetTimeDateFromUnix( hALStorage this_object,long unix_time );
/*
* Last minute additions, sorry, these 4 aren't in the manual!
*/
AL_LINKAGE void AL_FUNCTION
ALStorageGetTime( hALStorage this_object,
short int AL_DLL_FAR *hour,
short int AL_DLL_FAR *minute,
short int AL_DLL_FAR *second );
AL_LINKAGE void AL_FUNCTION
ALStorageSetTime( hALStorage this_object,
short int hour,
short int minute,
short int second );
AL_LINKAGE void AL_FUNCTION
ALStorageGetDate( hALStorage this_object,
short int AL_DLL_FAR *month,
short int AL_DLL_FAR *date,
short int AL_DLL_FAR *year );
AL_LINKAGE void AL_FUNCTION
ALStorageSetDate( hALStorage this_object,
short int month,
short int date,
short int year );
AL_LINKAGE int AL_FUNCTION ALStorageFlushBuffer( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION
ALStorageLoadBuffer( hALStorage this_object, long address );
AL_LINKAGE int AL_FUNCTION
ALStorageRename( hALStorage this_object,
char AL_DLL_FAR *new_name,
int delete_on_clash );
AL_LINKAGE int AL_FUNCTION
ALStorageRenameToBackup( hALStorage this_object, int delete_on_clash );
AL_LINKAGE int AL_FUNCTION ALStorageSeek( hALStorage this_object,
long address );
AL_LINKAGE int AL_FUNCTION ALStorageUnRename( hALStorage this_object,
int delete_on_clash );
AL_LINKAGE int AL_FUNCTION ALStorageGetType( hALStorage this_object );
AL_LINKAGE unsigned short int AL_FUNCTION
ALStorageGetDosTime( hALStorage this_object );
AL_LINKAGE unsigned short int AL_FUNCTION
ALStorageGetDosDate( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageValidTimeDate( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageReadOnly( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageSystem( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageHidden( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageArchive( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageDirectory( hALStorage this_object );
AL_LINKAGE long AL_FUNCTION ALStorageGetSize( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageIsOpen( hALStorage this_object );
AL_LINKAGE void AL_FUNCTION ALStorageClearError( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageReadChar( hALStorage this_object );
AL_LINKAGE int AL_FUNCTION ALStorageWriteChar( hALStorage this_object, int c );
#endif /* #if defined( __cplusplus ) ... #else ...*/
#endif /* #ifndef _STOR_H */