Table of Contents
Table of Contentsclass PtStoragePtStorage is used to store unstructured data in the database. To POET, the data in a PtStorage is just a series of bytes, and you can not do a query based on the values of a PtStorage. There are a lot of similarities between PtStorage and PtBlob, but PtStorage is pre-registered in the class dictionary as an _persistent class, and PtBlob is a type manager type. The implementation of PtStorage is generally more efficient than PtBlob, and PtStorage supports fast incremental saves, so there are real advantages to using PtStorage. PtStorage is the base class for PtOLEStorage, which is used to provide storage for OLE embedded objects in POET's IILockBytes implementation.
PtStorage: class summary| Files to include | Class declaration | Base class |
| ptstg.hxx | ptstg.hxx | PtObject |
| constructor | PtStorage(); |
| destructor | virtual ~PtStorage(); |
| Activate | virtual void Activate(); |
| ActivateReadAhead | void ActivateReadAhead(); |
| AllocateForRead | void AllocateForRead (PtStorageIterator &, PtDWord offset, PtDWord cb, void **pv, PtDWord *pcbRead); |
| AllocateForWrite | void AllocateForWrite (PtDWord offset, PtDWord cb, void **pv, PtDWord *pcbWrite); |
| EndCollectStore | int EndCollectStore(); |
| Flush | int Flush(); |
| GetSize | PtDWorddword GetSize(); |
| LockRegion | int LockRegion(PtDWorddword libOffset, PtDWorddword cb,PtLockMode lockMode); |
| ReadAhead | static unsigned short& ReadAhead(); |
| ReadAt | int ReadAt(PtDWorddword ulOffset, void *pv, PtDWorddword cb, PtDWorddword *pcbRead); |
| SetClusterCache | void SetClusterCache (PtClusterCache *); |
| SetSize | int SetSize(PtDWorddword cb); |
| StartCollectStore | void StartCollectStore(); |
| Store | virtual int Store(PtDepthMode Mode = PtDEEP); |
| UnlockRegion | int UnlockRegion(PtDWorddword libOffset, PtDWorddword cb, PtLockMode lockMode); |
| WriteAt | int WriteAt(PtDWorddword ulOffset, void const *pv, PtDWorddword cb, PtDWorddword *pcbWritten); |
PtStorage::PtStorage() - PtStorage::PtStorage()
- PtStorage::PtStorage(PtBase *, PtObjId *, PtPtr2SurrTuple*& )
Each of these is described separately below.
- PtStorage::PtStorage()
- PtStorage::PtStorage(PtBase *, PtObjId *, PtPtr2SurrTuple*& )
Class factory constructor. Do not use this, it is used by POET.
PtStorage::~PtStorage() - virtual PtStorage::~PtStorage()
- PtStorage::Activate()
Overrides PtObject:: Activate(). POET calls this function whenever a PtStorage is read from the database. Do not call this function explicitly.
PtStorage::ActivateReadAhead() - void PtStorage::ActivateReadAhead()
Do not use this function; it is used internally by POET.
PtStorage::AllocateForRead() - int PtStorage::AllocateForRead( PtStorageReadIterator &iterator,
- PtDWord offset, PtDWord cb, void ** pv, PtDWord *pcbRead)
Allocates space for future ReadAt() calls. This can be used to optimize performance. Note that this function is allowed to return less than the requested size.
| PtStorageReadIterator &iter | starting cluster |
| PtDWord offset | the offset relative to the starting cluster |
| PtDWord cb | "count bytes" - the number of bytes to allocate |
| void **pv | A pointer to the memory location of the allocated space will be set here. |
| PtDWord *pcbRead | The number of bytes allocated is returned here. |
| 0 | Success |
| ERR_PT_RANGE | Attempt to read behind the end of the PtStorage |
PtStorage::AllocateForWrite() - int PtStorage::AllocateForWrite( PtDWord offset, PtDWord cb, void ** pv, PtDWord *pcbWrite)
Allocates space for future WriteAt() calls. This can be used to optimize performance. Note that this function is allowed to grow the underlying PtCluster to the requested size.
| PtDWord offset | the offset relative to the starting cluster |
| PtDWord cb | "count bytes" - the number of bytes to allocate |
| void **pv | A pointer to the memory location of the allocated space will be set here. |
| PtDWord *pcbWrite | The number of bytes allocated is returned here. |
| 0 | Success |
| != 0 | see POET error codes |
PtStorage::EndCollectStore() - int PtStorage::EndCollectStore()
Do not use this function; it is used internally by POET.
PtStorage::Flush() - int PtStorage::Flush()
Writes all changes to disk.
PtStorage::GetSize() - PtDWorddword PtStorage::GetSize()
Returns the total number of bytes in the PtStorage.
PtStorage::LockRegion() - int PtStorage::LockRegion(PtDWorddword libOffset, PtDWorddword cb, PtLockMode lockMode)
Locks a region of memory by doing a PtObject:: Lock() on the relevant clusters. POET locks clusters, not individual bytes, so it may lock more than you specify in the parameter list.
| PtDWorddword libOffset | Starting offset to lock |
| PtDWorddword cb | "count bytes" - the number of bytes to lock |
| PtLockMode lockMode | Lock mode |
| 0 | Success |
| Non-zero | The result of the PtObject:: Lock() operation |
PtStorage::ReadAhead() - static unsigned short& PtStorage::ReadAhead()
Returns the number of clusters used for the read-ahead buffer. Because ReadAhead() returns this by reference, you can also use this function to set the size of the read-ahead buffer.
PtStorage::ReadAt() - int PtStorage::ReadAt(PtDWorddword ulOffset, void *pv, PtDWorddword cb, PtDWorddword *pcbRead)
Reads a series of bytes from the PtStorage.
| PtDWorddword ulOffset | The offset in the PtStorage at which the read should start |
| void *pv | A pointer to the buffer into which the bytes are to be read |
| PtDWorddword cb | "count bytes" - the number of bytes to be read |
| PtDWorddword *pcbRead | If non-zero, POET will write the number of bytes actually read into this position. If all the bytes could be read, this is the same value as the cb parameter. |
| 0 | Success |
| non-zero | Read error |
PtStorage::SetClusterCache() - vod PtStorage::SetClusterCache( PtClusterCache *newCache)
Destroys the current cache and sets the new cache.
| PtClusterCache *newCache | Pointer to the nw cluster cache |
PtStorage::SetSize() - int PtStorage::SetSize(PtDWorddword cb)
Sets the size of the storage. If the new size is larger than the previous size, SetSize() adds uninitialized clusters. If it is smaller, SetSize() deletes clusters from the end.
| PtDWorddword cb | "count bytes" - the new size for the buffer |
| 0 | Success |
| non-zero | Error |
PtStorage::StartCollectStore() - void PtStorage::StartCollectStore()
Do not use this function; it is used internally by POET.
PtStorage::Store() - virtual int PtStorage::Store(PtDepthMode Mode = PtDEEP)
This function works just like PtObject:: Store(), but is optimized for PtStorage.
PtStorage::UnlockRegion() - int PtStorage::UnlockRegion(PtDWorddword libOffset, PtDWorddword cb, PtLockMode lockMode)
Unlocks a region which was locked using LockRegion(). The parameters must agree with those used to set the lock using LockRegion().
| PtDWorddword libOffset | Offset to the region which is to be unlocked |
| PtDWorddword cb | "count bytes" - the number of bytes to be unlocked |
| PtLockMode lockMode | The lock mode for the original lock which is being removed |
| 0 | success |
| non-zero | error |
PtStorage::WriteAt() - int PtStorage::WriteAt(PtDWorddword ulOffset, void const *pv, PtDWorddword cb, PtDWorddword *pcbWritten)
Writes data into the PtStorage. This write is done inside an internal transaction, and the changes are not written to the database until you do a Flush().
| PtDWorddword ulOffset | The starting offset to which the data should be written in the PtStorage |
| void const *pv | A pointer to the data in RAM |
| PtDWorddword cb | "count bytes" - the number of bytes to be written |
| PtDWorddword *pcbWritten | If non-zero, POET will write the number of bytes actually written into this position. If all the bytes could be written, this is the same value as the cb parameter. |
Copyright (c) 1996 POET Software, Inc. All rights reserved. Reproduction in whole or in part in any form or medium without the express permission of POET Software, Inc. is prohibited.