| Exiv2

Loading...
Searching...
No Matches
Classes | List of all members
Exiv2::MemIo Class Reference

Provides binary IO on blocks of memory by implementing the BasicIo interface. A copy-on-write implementation ensures that the data passed in is only copied when necessary, i.e., as soon as data is written to the MemIo. The original data is only used for reading. If writes are performed, the changed data can be retrieved using the read methods (since the data used in construction is never modified). More...

`#include <basicio.hpp>`

Inheritance diagram for Exiv2::MemIo:
[legend]

## Classes
class | Impl
| Internal Pimpl structure of class MemIo. More...

## Public Member Functions
Creators
| MemIo ()
| Default constructor that results in an empty object.
| MemIo (const byte *data, size_t size)
| Constructor that accepts a block of memory. A copy-on-write algorithm allows read operations directly from the original data and will create a copy of the buffer on the first write operation.
| ~MemIo () override
| Destructor. Releases all managed memory.
Manipulators
int | open () override
| Memory IO is always open for reading and writing. This method therefore only resets the IO position to the start.
int | close () override
| Does nothing on MemIo objects.
size_t | write (const byte *data, size_t wcount) override
| Write data to the memory block. If needed, the size of the internal memory block is expanded. The IO position is advanced by the number of bytes written.
size_t | write (BasicIo &src) override
| Write data that is read from another BasicIo instance to the memory block. If needed, the size of the internal memory block is expanded. The IO position is advanced by the number of bytes written.
int | putb (byte data) override
| Write one byte to the memory block. The IO position is advanced by one byte.
DataBuf | read (size_t rcount) override
| Read data from the memory block. Reading starts at the current IO position and the position is advanced by the number of bytes read.
size_t | read (byte *buf, size_t rcount) override
| Read data from the memory block. Reading starts at the current IO position and the position is advanced by the number of bytes read.
int | getb () override
| Read one byte from the memory block. The IO position is advanced by one byte.
void | transfer (BasicIo &src) override
| Clear the memory block and then transfer data from the src BasicIo object into a new block of memory.
int | seek (int64_t offset, Position pos) override
| Move the current IO position.
byte * | mmap (bool=false) override
| Allow direct access to the underlying data buffer. The buffer is not protected against write access in any way, the argument is ignored.
int | munmap () override
| Remove a mapping established with mmap(). If the mapped area is writeable, this ensures that changes are written back.
Public Member Functions inherited from Exiv2::BasicIo
virtual | ~BasicIo ()=default
| Destructor.
void | readOrThrow (byte *buf, size_t rcount, ErrorCode err=ErrorCode::kerCorruptedMetadata)
| Safe version of read() that checks for errors and throws an exception if the read was unsuccessful.
void | seekOrThrow (int64_t offset, Position pos, ErrorCode err)
| Safe version of seek() that checks for errors and throws an exception if the seek was unsuccessful.

## Accessors
size_t | tell () const override
| Get the current IO position.
size_t | size () const override
| Get the current memory buffer size in bytes.
bool | isopen () const override
| Always returns true.
int | error () const override
| Always returns 0.
bool | eof () const override
| Returns true if the IO position has reached the end, otherwise false.
const std::string & | path () const noexcept override
| Returns a dummy path, indicating that memory access is used.
void | populateFakeData () override
| Mark all the bNone blocks to bKnow. This avoids allocating memory for parts of the file that contain image-date (non-metadata/pixel data).
| MemIo (const MemIo &)=delete
| Copy constructor.
MemIo & | operator= (const MemIo &)=delete
| Assignment operator.

## Additional Inherited Members
Public Types inherited from Exiv2::BasicIo
enum | Position { beg , cur , end }
| Seek starting positions.
using | UniquePtr = std::unique_ptr<BasicIo>
| BasicIo auto_ptr type.
byte * | bigBlock_ {}
| this is allocated and populated by mmap()

## Detailed Description

Provides binary IO on blocks of memory by implementing the BasicIo interface. A copy-on-write implementation ensures that the data passed in is only copied when necessary, i.e., as soon as data is written to the MemIo. The original data is only used for reading. If writes are performed, the changed data can be retrieved using the read methods (since the data used in construction is never modified).

Note
  If read only usage of this class is common, it might be worth creating a specialized readonly class or changing this one to have a readonly mode.

## Constructor & Destructor Documentation

## ◆ MemIo()

Exiv2::MemIo::MemIo | ( | const byte * | data,
|  | size_t | size )

Constructor that accepts a block of memory. A copy-on-write algorithm allows read operations directly from the original data and will create a copy of the buffer on the first write operation.

Parameters

  data | Pointer to data. Data must be at least size bytes long
  size | Number of bytes to copy.

References size().

## Member Function Documentation

## ◆ close()

int Exiv2::MemIo::close | ( |  | ) |
| override virtual

Does nothing on MemIo objects.

Returns
  0

Implements Exiv2::BasicIo.

## ◆ eof()

bool Exiv2::MemIo::eof | ( |  | ) | const
| nodiscard override virtual

Returns true if the IO position has reached the end, otherwise false.

Implements Exiv2::BasicIo.

## ◆ error()

int Exiv2::MemIo::error | ( |  | ) | const
| nodiscard override virtual

Always returns 0.

Implements Exiv2::BasicIo.

Referenced by transfer(), and Exiv2::XmpSidecar::writeMetadata().

## ◆ getb()

int Exiv2::MemIo::getb | ( |  | ) |
| override virtual

Read one byte from the memory block. The IO position is advanced by one byte.

Returns
  The byte read from the memory block if successful;
  EOF if failure;

Implements Exiv2::BasicIo.

## ◆ isopen()

bool Exiv2::MemIo::isopen | ( |  | ) | const
| nodiscard override virtual

Always returns true.

Implements Exiv2::BasicIo.

## ◆ mmap()

byte * Exiv2::MemIo::mmap | ( | bool | = false | ) |
| override virtual

Allow direct access to the underlying data buffer. The buffer is not protected against write access in any way, the argument is ignored.

Note
  The application must ensure that the memory pointed to by the returned pointer remains valid and allocated as long as the MemIo object exists.

Implements Exiv2::BasicIo.

Referenced by Exiv2::Internal::TiffBinaryArray::doWrite(), and Exiv2::ExifParser::encode().

## ◆ munmap()

int Exiv2::MemIo::munmap | ( |  | ) |
| override virtual

Remove a mapping established with mmap(). If the mapped area is writeable, this ensures that changes are written back.

Returns
  0 if successful;
  Nonzero if failure;

Implements Exiv2::BasicIo.

## ◆ open()

int Exiv2::MemIo::open | ( |  | ) |
| override virtual

Memory IO is always open for reading and writing. This method therefore only resets the IO position to the start.

Returns
  0

Implements Exiv2::BasicIo.

## ◆ path()

const std::string & Exiv2::MemIo::path | ( |  | ) | const
| nodiscard override virtual noexcept

Returns a dummy path, indicating that memory access is used.

Implements Exiv2::BasicIo.

## ◆ populateFakeData()

void Exiv2::MemIo::populateFakeData | ( |  | ) |
| override virtual

Mark all the bNone blocks to bKnow. This avoids allocating memory for parts of the file that contain image-date (non-metadata/pixel data).

Note
  This method should be only called after the concerned data (metadata) are all downloaded from the remote file to memory.

Implements Exiv2::BasicIo.

## ◆ putb()

int Exiv2::MemIo::putb | ( | byte | data | ) |
| override virtual

Write one byte to the memory block. The IO position is advanced by one byte.

Parameters

  data | The single byte to be written.

Returns
  The value of the byte written if successful;
  EOF if failure;

Implements Exiv2::BasicIo.

## ◆ read() [1/2]

size_t Exiv2::MemIo::read | ( | byte * | buf,
|  | size_t | rcount )
| override virtual

Read data from the memory block. Reading starts at the current IO position and the position is advanced by the number of bytes read.

Parameters

  buf | Pointer to a block of memory into which the read data is stored. The memory block must be at least rcount bytes long.
  rcount | Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.

Returns
  Number of bytes read from the memory block successfully;
  0 if failure;

Implements Exiv2::BasicIo.

## ◆ read() [2/2]

DataBuf Exiv2::MemIo::read | ( | size_t | rcount | ) |
| override virtual

Read data from the memory block. Reading starts at the current IO position and the position is advanced by the number of bytes read.

Parameters

  rcount | Maximum number of bytes to read. Fewer bytes may be read if rcount bytes are not available.

Returns
  DataBuf instance containing the bytes read. Use the DataBuf::size_ member to find the number of bytes read. DataBuf::size_ will be 0 on failure.

Implements Exiv2::BasicIo.

References Exiv2::DataBuf::data(), read(), and Exiv2::DataBuf::resize().

Referenced by read().

## ◆ seek()

int Exiv2::MemIo::seek | ( | int64_t | offset,
|  | Position | pos )
| override virtual

Move the current IO position.

Parameters

  offset | Number of bytes to move the position relative to the starting position specified by pos
  pos | Position from which the seek should start

Returns
  0 if successful;
  Nonzero if failure;

Implements Exiv2::BasicIo.

Referenced by Exiv2::Internal::TiffBinaryArray::doWrite().

## ◆ size()

size_t Exiv2::MemIo::size | ( |  | ) | const
| nodiscard override virtual

Get the current memory buffer size in bytes.

Returns
  Size of the in memory data in bytes;
  -1 if failure;

Implements Exiv2::BasicIo.

Referenced by Exiv2::Internal::TiffBinaryArray::doWrite(), Exiv2::ExifParser::encode(), Exiv2::MemIo::Impl::Impl(), Exiv2::MemIo::Impl::Impl(), MemIo(), and Exiv2::MemIo::Impl::reserve().

## ◆ tell()

size_t Exiv2::MemIo::tell | ( |  | ) | const
| nodiscard override virtual

Get the current IO position.

Returns
  Offset from the start of the memory block

Implements Exiv2::BasicIo.

## ◆ transfer()

void Exiv2::MemIo::transfer | ( | BasicIo & | src | ) |
| override virtual

Clear the memory block and then transfer data from the src BasicIo object into a new block of memory.

This method is optimized to simply swap memory block if the source object is another MemIo instance. The source BasicIo instance is invalidated by this operation and should not be used after this method returns. This method exists primarily to be used with the BasicIo::temporary() method.

Parameters

  src | Reference to another BasicIo instance. The entire contents of src are transferred to this object. The src object is invalidated by the method.

Exceptions

  Error | In case of failure

Implements Exiv2::BasicIo.

References Exiv2::BasicIo::close(), Exiv2::BasicIo::error(), error(), MemIo(), Exiv2::BasicIo::open(), Exiv2::BasicIo::path(), Exiv2::strError(), and write().

## ◆ write() [1/2]

size_t Exiv2::MemIo::write | ( | BasicIo & | src | ) |
| override virtual

Write data that is read from another BasicIo instance to the memory block. If needed, the size of the internal memory block is expanded. The IO position is advanced by the number of bytes written.

Parameters

  src | Reference to another BasicIo instance. Reading start at the source's current IO position

Returns
  Number of bytes written to the memory block successfully;
  0 if failure;

Implements Exiv2::BasicIo.

References Exiv2::BasicIo::isopen(), Exiv2::BasicIo::read(), and write().

## ◆ write() [2/2]

size_t Exiv2::MemIo::write | ( | const byte * | data,
|  | size_t | wcount )
| override virtual

Write data to the memory block. If needed, the size of the internal memory block is expanded. The IO position is advanced by the number of bytes written.

Parameters

  data | Pointer to data. Data must be at least wcount bytes long
  wcount | Number of bytes to be written.

Returns
  Number of bytes written to the memory block successfully;
  0 if failure;

Implements Exiv2::BasicIo.

Referenced by Exiv2::Internal::TiffBinaryArray::doWrite(), Exiv2::JpegBase::printStructure(), transfer(), write(), Exiv2::CrwImage::writeMetadata(), and Exiv2::XmpSidecar::writeMetadata().

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

- basicio.hpp
- basicio.cpp