XMP Toolkit SDK  6.0.0
XMP_IO Class Referenceabstract

Abstract base class for client-managed I/O with TXMPFiles. More...

#include <XMP_IO.hpp>

Public Types

enum  { kReadAll = true }
 

Public Member Functions

virtual XMP_Uns32 Read (void *buffer, XMP_Uns32 count, bool readAll=false)=0
 Read into a buffer, returning the number of bytes read. More...
 
XMP_Uns32 ReadAll (void *buffer, XMP_Uns32 bytes)
 
virtual void Write (const void *buffer, XMP_Uns32 count)=0
 Write from a buffer. More...
 
virtual XMP_Int64 Seek (XMP_Int64 offset, SeekMode mode)=0
 Set the I/O position, returning the new absolute offset in bytes. More...
 
XMP_Int64 Offset ()
 
XMP_Int64 Rewind ()
 
XMP_Int64 ToEOF ()
 
virtual XMP_Int64 Length ()=0
 Return the length of the file in bytes. More...
 
virtual void Truncate (XMP_Int64 length)=0
 Truncate the file to the given length. More...
 
virtual XMP_IODeriveTemp ()=0
 Create an associated temp file for use in a safe-save style operation. More...
 
virtual void AbsorbTemp ()=0
 Replace the owning file's content with that of the temp. More...
 
virtual void DeleteTemp ()=0
 Delete a temp file, leaving the original alone. More...
 
 XMP_IO ()
 
virtual ~XMP_IO ()
 

Private Member Functions

 XMP_IO (const XMP_IO &original)
 
void operator= (const XMP_IO &)
 

Detailed Description

Abstract base class for client-managed I/O with TXMPFiles.

XMP_IO is an abstract base class for client-managed I/O with TXMPFiles. This allows a client to use the embedded metadata processing logic of TXMPFiles in cases where a string file path cannot be provided, or where it is impractical to allow TXMPFiles to separately open the file and do its own I/O. Although described in terms of files, any form of storage may be used as long as the functions operate as defined.

This is not a general purpose I/O class. It contains only the necessary functions needed by the internals of TXMPFiles. It is intended to be used as an adaptor for an existing I/O mechanism that the client wants TXMPFiles to use.

To use XMP_IO, a client creates a derived class then uses the form of TCMPFiles::OpenFile that takes an XMP_IO parameter instead of a string file path. The derived XMP_IO object must be ready for use when TCMPFiles::OpenFile is called.

There are no Open or Close functions in XMP_IO, they are specific to each implementation. The derived XMP_IO object must be open and ready for use before being passed to TXMP_Files::OpenFile, and remain open and ready for use until TXMP_Files::CloseFile returns, or some other fatal error occurs. The client has final responsibility for closing and terminating the derived XMP_IO object.

Definition at line 44 of file XMP_IO.hpp.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
Enumerator
kReadAll 

Definition at line 46 of file XMP_IO.hpp.

46 { kReadAll = true };

Constructor & Destructor Documentation

◆ XMP_IO() [1/2]

XMP_IO::XMP_IO ( )
inline

Definition at line 157 of file XMP_IO.hpp.

157 {};

◆ ~XMP_IO()

virtual XMP_IO::~XMP_IO ( )
inlinevirtual

Definition at line 158 of file XMP_IO.hpp.

158 {};

◆ XMP_IO() [2/2]

XMP_IO::XMP_IO ( const XMP_IO original)
private

Copy construction and assignment are not public. That would require the implementation to share state across multiple XMP_IO objects.

Member Function Documentation

◆ AbsorbTemp()

virtual void XMP_IO::AbsorbTemp ( )
pure virtual

Replace the owning file's content with that of the temp.

Used at the end of a safe-save style operation to replace the original content with that from the associated temp file. The temp file must be closed and deleted after the content swap. The temporary XMP_IO object is deleted. Throws an exception if the temp file cannot be absorbed. Throwing XMPError is recommended.

◆ DeleteTemp()

virtual void XMP_IO::DeleteTemp ( )
pure virtual

Delete a temp file, leaving the original alone.

Used for a failed safe-save style operation. The temp file is closed and deleted without being absorbed, and the temporary XMP_IO object is deleted. Does nothing if no temp exists.

◆ DeriveTemp()

virtual XMP_IO* XMP_IO::DeriveTemp ( )
pure virtual

Create an associated temp file for use in a safe-save style operation.

Create an associated temp file, for example in the same directory and with a related name. Returns an already existing temp with no other action. The temp must be opened for read-write access. It will be used in a safe-save style operation, using some of the original file plus new portions to write the temp, then replacing the original from the temp when done. Throws an exception if the owning object is opened for read-only access, or if the temp file cannot be created. Throwing XMPError is recommended.

The temp file is normally closed and deleted, and the temporary XMP_IO object deleted, by a call to AbsorbTemp or DeleteTemp. It must be closed and deleted by the derived XMP_IO object's destructor if necessary.

DeriveTemp may be called on a temporary XMP_IO object.

Returns
A pointer to the associated temporary XMP_IO object.

◆ Length()

virtual XMP_Int64 XMP_IO::Length ( )
pure virtual

Return the length of the file in bytes.

Return the length of the file in bytes. The I/O position is unchanged.

Returns
The length of the file in bytes.

◆ Offset()

XMP_Int64 XMP_IO::Offset ( )
inline

Definition at line 92 of file XMP_IO.hpp.

92 { return this->Seek ( 0, kXMP_SeekFromCurrent ); };

References kXMP_SeekFromCurrent, and Seek().

◆ operator=()

void XMP_IO::operator= ( const XMP_IO )
inlineprivate

this = in;

Definition at line 167 of file XMP_IO.hpp.

167 { /* Avoid Win compile warnings. */ };

◆ Read()

virtual XMP_Uns32 XMP_IO::Read ( void *  buffer,
XMP_Uns32  count,
bool  readAll = false 
)
pure virtual

Read into a buffer, returning the number of bytes read.

Read into a buffer, returning the number of bytes read. Returns the actual number of bytes read. Throws an exception if requireSuccess is true and not enough data is available. Throwing XMPError is recommended. The buffer content and I/O position after a throw are undefined.

Parameters
bufferA pointer to the buffer.
countThe length of the buffer in bytes.
readAllTrue if reading less than the requested amount is a failure.
Returns
Returns the number of bytes read.

Referenced by ReadAll().

◆ ReadAll()

XMP_Uns32 XMP_IO::ReadAll ( void *  buffer,
XMP_Uns32  bytes 
)
inline

Definition at line 63 of file XMP_IO.hpp.

64  { return this->Read ( buffer, bytes, kReadAll ); };

References kReadAll, and Read().

◆ Rewind()

XMP_Int64 XMP_IO::Rewind ( )
inline

Definition at line 93 of file XMP_IO.hpp.

93 { return this->Seek ( 0, kXMP_SeekFromStart ); }; // Always returns 0.

References kXMP_SeekFromStart, and Seek().

◆ Seek()

virtual XMP_Int64 XMP_IO::Seek ( XMP_Int64  offset,
SeekMode  mode 
)
pure virtual

Set the I/O position, returning the new absolute offset in bytes.

Set the I/O position, returning the new absolute offset in bytes. The offset parameter may be positive or negative. A seek beyond EOF is allowed when writing and extends the file, it is equivalent to seeking to EOF then writing the needed amount of undefined data. A read-only seek beyond EOF throws an exception. Throwing XMPError is recommended.

Parameters
offsetThe offset relative to the mode.
modeThe mode, or origin, of the seek.
Returns
The new absolute offset in bytes.

Referenced by Offset(), Rewind(), and ToEOF().

◆ ToEOF()

XMP_Int64 XMP_IO::ToEOF ( )
inline

Definition at line 94 of file XMP_IO.hpp.

94 { return this->Seek ( 0, kXMP_SeekFromEnd ); };

References kXMP_SeekFromEnd, and Seek().

◆ Truncate()

virtual void XMP_IO::Truncate ( XMP_Int64  length)
pure virtual

Truncate the file to the given length.

Truncate the file to the given length. The I/O position after truncation is unchanged if still valid, otherwise it is set to the new EOF. Throws an exception if the new length is longer than the file's current length. Throwing XMPError is recommended.

Parameters
lengthThe new length for the file, must be less than or equal to the current length.

◆ Write()

virtual void XMP_IO::Write ( const void *  buffer,
XMP_Uns32  count 
)
pure virtual

Write from a buffer.

Write from a buffer, overwriting existing data and extending the file as necesary. All data must be written or an exception thrown. Throwing XMPError is recommended.

Parameters
bufferA pointer to the buffer.
countThe length of the buffer in bytes.

The documentation for this class was generated from the following file:
kXMP_SeekFromEnd
@ kXMP_SeekFromEnd
Definition: XMP_Const.h:876
kXMP_SeekFromCurrent
@ kXMP_SeekFromCurrent
Definition: XMP_Const.h:876
XMP_IO::kReadAll
@ kReadAll
Definition: XMP_IO.hpp:46
XMP_IO::Seek
virtual XMP_Int64 Seek(XMP_Int64 offset, SeekMode mode)=0
Set the I/O position, returning the new absolute offset in bytes.
kXMP_SeekFromStart
@ kXMP_SeekFromStart
Definition: XMP_Const.h:876
XMP_IO::Read
virtual XMP_Uns32 Read(void *buffer, XMP_Uns32 count, bool readAll=false)=0
Read into a buffer, returning the number of bytes read.