| XMP Toolkit SDK 6.0.0

Public Types | Public Member Functions | Private Member Functions | List of all members
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_IO * | DeriveTemp ()=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 | ( |  | ) |
| inline virtual

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 & |  | ) |
| inline private

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

  buffer | A pointer to the buffer.
  count | The length of the buffer in bytes.
  readAll | True 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

  offset | The offset relative to the mode.
  mode | The 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

  length | The 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

  buffer | A pointer to the buffer.
  count | The length of the buffer in bytes.

The documentation for this class was generated from the following file:

- public/include/XMP_IO.hpp

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.