Aldebaran documentation What's new in NAOqi 2.4.3?

qi::File

Summary

qi::File provides a way to open a file in read-only mode on the local file system and share the content of this file with potentially remote services.

We provide algorithms to copy a remote file’s content to make a local copy of it, using the qi::copyToLocal or qi::prepareCopyToLocal functions.

Detailed Usage Description

Opening a file in read-only mode for sharing access

Use qi::openLocalFile to open the file in sharing read-only mode:

qi::FilePtr file = qi::openLocalFile("valid/path/to/file.ext");

In this example, the file object can be passed to a service API requesting a qi::FilePtr, making the content of the file available to the service even if remote.

If the file does not exist, a std::runtime_error exception will be thrown.

File access lifetime

The lifetime of the file access is extended by the shared ownership between all the qi::FilePtr, even if the instance is remote.

The qi::File object is kept alive and the file access open by default until all qi::FilePtr objects referring owning it are destroyed. The file access is automatically closed when qi::File is destroyed.

Once you don’t need it anymore and want to explicitly stop owning the access, you can use the qi::FilePtr::reset member of qi::FilePtr. The file access will be closed if there is no other owner still using it.

void someServiceOperation(qi::FilePtr file)
{
  // Do some work  with file...

  // No need to work with the file anymore.
  file.reset(); // From now on, `file` is not usable anymore.
  // If we were the only one accessing this file,
  // access to it's content is now closed.

  //...

  file->isOpen(); // ERROR
}

Request or provide read-only access to the content of a file

A service can request read-only access to the content of a file by using qi::FilePtr as argument.

Similarly, a service can provide read-only access to a file by having a function return a qi::FilePtr.

For example:

class MY_API MyService
{
  //...
public:

  // Store a copy of the provided file, associated with the provided name.
  void storeFile(qi::FilePtr fileToStore, const std::string& name);

  // Provide access to a stored file found by name.
  qi::FilePtr getFile(const std::string& name);

  //...
};

typedef qi::Object<MyService> MyServicePtr;

In this example, the user of the service can provide access to a file this way:

void backup(MyServicePtr service, const std::string& name, const qi::Path& fileToStore)
{
  qi::FilePtr file = qi::openLocalFile(fileToStore);
  // Now we can share reading access to this file.
  service->storeFile(file, name);
  // At this point, the service have a copy of the file and can start to work with it.
}

and acquire access to a file content provided by the service this way:

void restore(MyServicePtr service, const std::string& name)
{
  // Get Access to the file.
  qi::FilePtr file = service->getFile(name);

  if(file)
  {
    // Then work with the file content.
    // ...
  }
}

Make a local copy of a provided file

We can use the qi::copyToLocal function to make a local copy of the file provided through a qi::FilePtr. The qi::copyToLocal function will transfer a copy of the content of the file to the local file system, even if the original file is on a remote file system.

For example, if we want a service function to make a full copy of a provided file, in a local temporary location, before doing any more work:

void MyService::storeFile(qi::FilePtr fileToStore, const std::string& name)
{
  // First, make a local copy in a temporary files directory:
  const qi::Path tempFilePath = generateTemporaryFilePath();
  qi::copyToLocal(fileToStore, tempFilePath); // This call wait for the end of the copy.

  // We now have a local copy of the remote file,
  // we don't need the remote access anymore.
  fileToStore.reset();

  // Now we can work with the local copy of the file:
  storeFileInDatabase(name, tempFilePath);
}

In the same way, we can provide access to the data of the file by returning a qi::FilePtr:

FilePtr MyService::getFile(const std::string& name)
{
  const qi::Path fileLocation = findFileLocation(name);

  if (fileLocation.exists() && fileLocation.isfile())
  {
    // Now we can open it and provide it to the user for reading.
    return qi::openLocalFile(fileLocation);
  }

  // We didn't find the file!
  return FilePtr();
}

Then the user can retrieve a copy of the file and work with it:

void restore(MyServicePtr service, const std::string& name, const qi::Path& fileLocation)
{
  // Get access to the file.
  qi::FilePtr file = service->getFile(name);

  if (file) // The file was found.
  {
    // We want to make a local copy before working on the file.
    qi::copyToLocal(file, fileLocation);

    // We don't need the remote access anymore.
    file.reset();

    // Now work on the file located at `fileLocation`.
    workOnFile(fileLocation);
  }
}

Observe the progression of a file copy, transfer or other long operations

Potentially long file operations like qi::copyToLocal returns a qi::FutureSync. This imply that the call will wait for the end of the operation if the qi::FutureSync is not used by the user or not put into a qi::Future for later usage.

To wait for the end of the operation, we just wait for the future to be set:

void printFinished()
{
  qiLogInfo() << "File Transfer Finished! ";
}

void fetchFile(qi::FilePtr file)
{
    const qi::Path temporaryFilePath = makeTemporaryFilePath();

    // We copy the file on a temporary work location on the local filesystem,
    // but we don't wait for the transfer to end.
    qi::Future<void> transfer = qi::copyToLocal(file, temporaryFilePath);

    // We want to log the end of the transfer:
    transfer.connect(&printFinished);

    // Do some additional work while the file is transfered.
    someAdditionalWork();

    // Now we wait until the end of the operation if it's not finished yet.
    transfer.wait(); // Don't wait for futures in real code, you should .connect() instead.
    file.reset();

    workOnFile(temporaryFilePath);
}

In this example we want to be notified about the end of the operation, so we can connect a callback to the future. However, using only a future, we cannot get progress information about the transfer.

To get progress information and be able to connect callbacks to the different steps of the operation before the operation starts, we can use the qi::prepareCopyToLocal function instead of qi::copyToLocal function:

void printStatus(qi::FileOperation::Status status)
{
  switch(status)
  {
    case Status_Finished:
      qiLogInfo() << "File Transfer Finished! ";
      break;

    case Status_Failed:
      qiLogInfo() << "File Transfer Failed! ";
      break;

     case Status_Canceled:
      qiLogInfo() << "File Transfer Canceled! ";
      break;
  }
  // We ignore the other status.
}

void printProgress(double progress)
{
  qiLogInfo() << "#### File Transfer Progress = " << (progress * 100.0) << "%";
}

void fetchFile(qi::FilePtr file)
{
    const qi::Path temporaryFilePath = makeTemporaryFilePath();

    // Instead of launching the copy immediately, we prepare it by setting up
    // the object which represent that operation.
    qi::FileOperation fileCopy = qi::prepareCopyToLocal(file, temporaryFilePath);

    // We want to log the state changes of the transfer.
    fileCopy.status.connect(&printStatus);

    // We also to log the progress of the transfer.
    fileCopy.progress.connect(&printProgress);

    // We are ready to launch the copy now.
    Future<void> ft = fileCopy.start();

    // Do some additional work while the file is transfered.
    someAdditionalWork();

    // Now we wait until the end of the operation if it's not finished yet.
    ft.wait(); // Don't wait for futures in real code, you should .connect() instead.

    // We don't need the file access anymore.
    file.reset();

    workOnFile(temporaryFilePath);
}

The qi::prepareCopyToLocal function builds a qi::FileOperation which represents the copy/transfer operation but does not start it. As this example demonstrates, the user can then plug callbacks to signals and properties provided by qi::ProgressNotifier which is the base class of qi::FileOperation. The user can then start the copy operation by calling the qi::FileOperation::start() member function.

Similarly, the side of the code which opened the file and provided access to it can also follow the progression of the on-going operations on the file by using the qi::File::operationProgress member function. This function provides access to a qi::ProgressNotifier which is updated by the current file operation on the file.

void printStatus(qi::FileOperation::Status status); // as before
void printProgress(double progress); // as before

void storeFile(MyServicePtr service, const std::string& name, const qi::Path& fileToStore)
{
  qi::FilePtr file = qi::openLocalFile(fileToStore);

  // Before sending the access to the file, connect progress logging callbacks.
  qi::ProgressNotifierPtr copyProgress = file.operationProgress()
  copyProgress.status.connect(&printFinished);
  copyProgress.progress.connect(&printProgress);

  // Now we can share reading access to this file.
  service->storeFile(file, name);

  // At this point, the service have a copy of the file and can start to work with it.
}

Complete example : Alice’s Image Store Service

The following code samples are extracted from the complete example project located in the worktree at sdk/libqicore/libqicore/example/file/

In this example, Alice design a naoqi service which provide storage for images files. Then Bob writes an application which access Alice’s image storage service and work with it.

ImageStore

Alice’s ImageStore service is simple and straightforward:

This is very similar to the example code in previous sections. In particular:

Note the qi::FilePtr usage which allow the user to provide access to a file, or to acquire a stored file access.

To implement the storeImage function, Alice first acquire and copy the user file in a temporary location, then do some work to register it in the store’s database.

This is of course a simpler implementation, similar to the getImage function implementation:

ImageStore User Code

Meanwhile, Bob wrote his application to acquire Alice’s ImageStore instance, than do some basic work with it.

Reference

FilePtr qi::openLocalFile(const qi::Path& localPath)

Brief:

Parameters:
  • localPath – Path to a file on the local file system that can be open.
Returns:

A shareable access to the opened local file.

Open a local file located at the specified path and provide it for reading as a sharable file access.

FutureSync<void> qi::copyToLocal(FilePtr file, const Path& localPath)

Brief:

Parameters:
  • file – Source file to copy.
  • localPath – Local filesystem location where the specified file will be copied. No file or directory should be located at this path otherwise the operation will fail.
Returns:

A synchronous future associated with the operation.

Copy an open local or remote file to a local filesystem location.

FileOperationPtr qi::prepareCopyToLocal(FilePtr file, const Path& localPath)

Brief:

Parameters:
  • file – Source file to copy.
  • localPath – Local filesystem location where the specified file will be copied. No file or directory should be located at this path otherwise the operation will fail.
Returns:

This operation ready to be started but not executed yet.

Setup the following operation: a copy of local or remote file to a local filesystem location.

ProgressNotifierPtr qi::createProgressNotifier()

Brief:

Returns:Create and provide a remotely shareable ProgressNotifier object.
typedef qi::Object< File > FilePtr
Pointer to a file with shared/remote semantic.
typedef boost::shared_ptr< FileOperation > FileOperationPtr
Pointer to a file operation.
typedef qi::Object< ProgressNotifier > ProgressNotifierPtr
Pointer to a ProgressNotifier with shared/remote semantic.

qi::File Class Reference

Introduction

More...

#include <qicore/file.hpp>

Public Members

const std::streamsize MAX_READ_SIZE

Public Functions

~File()
std::streamsize size() const
bool isOpen() const
bool isRemote() const
ProgressNotifierPtr operationProgress() const
Buffer _read(std::streamsize countBytesToRead)
Buffer _read(std::streamoff beginOffset, std::streamsize countBytesToRead)
bool _seek(std::streamoff offsetFromBegin)
void _close()

Detailed Description

Provide access to the content of a local or remote file. Should be obtained using openLocalFile() or through a service API if the file is potentially remote.

Members Documentation

const std::streamsize qi::File::MAX_READ_SIZE

Maximum count of bytes that you can read by reading functions call.

Function Documentation

qi::File::~File()
std::streamsize qi::File::size() const = 0

Brief:

Returns:Total count of bytes contained in the file or 0 if the file is closed.
bool qi::File::isOpen() const = 0

Brief:

Returns:true if the file is currently open for reading, false otherwise.
bool qi::File::isRemote() const = 0

Brief:

Returns:true if the file is located on a remote filesystem, false otherwise.
ProgressNotifierPtr qi::File::operationProgress() const = 0

Provide the progress notifier used by the operations manipulating this file. The notifier is associated with this file. Therefore, no concurrent operation should be used by this notifier object, as it is not safe to have concurrent operations running on the same file.

Buffer qi::File::_read(std::streamsize countBytesToRead) = 0

Brief:

Parameters:
  • countBytesToRead – Count of bytes to read from the file, starting from the current position of the file cursor.
Returns:

A buffer of data read from the file, empty if there is no data in the specified byte range to read or if the file have been closed. If there is less data to read in the file than the required count, if we try reading past the end of the file for example, then the buffer will only contain the available data, nothing more.

Read a specified count of bytes starting from the current cursor position.

Buffer qi::File::_read(std::streamoff beginOffset, std::streamsize countBytesToRead) = 0

Brief:

Parameters:
  • beginOffset – Position in the file to start reading from.
  • countBytesToRead – Count of bytes to read from the file starting at the current position of the file cursor.
Returns:

A buffer of data read from the file, empty if: there is no data in the specified byte range to readif the file have been closed;if the start position is outside the available range of data in the file. If there is less data to read in the file than the required count, if we try reading past the end of the file for example, then the buffer will only contain the available data, nothing more

Read a specified count of bytes starting from a specified byte position in the file.

bool qi::File::_seek(std::streamoff offsetFromBegin) = 0

Brief:

Parameters:
  • offsetFromBegin – New position of the read cursor in the file. If it is out of the range of data in the file, the cursor will not be changed at all.
Returns:

true if the position is in the range of data available in the file, false otherwise, in which case the cursor have not been changed.

Move the read cursor to the specified position in the file.

void qi::File::_close() = 0

Close the file. Once this function is called, calling most other operation will throw a std::runtime_error. The size(), isOpen() and isRemote() calls will return work as expected.

qi::ProgressNotifier Class Reference

Introduction

More...

#include <qicore/file.hpp>

Enumerations

enum Status
Name Brief
Status_Idle The operation has not start yet.
Status_Running The operation is currently running.
Status_Finished The operation finished successfully.
Status_Failed The operation has failed.
Status_Cancelled The operation has been canceled by the user.

Public Members

Property<Status> status
Property<double> progress

Public Functions

~ProgressNotifier()
bool isRunning() const
void _reset()
void _notifyRunning()
void _notifyFinished()
void _notifyCancelled()
void _notifyFailed()
void _notifyProgressed(double newProgress)

Detailed Description

Provide information about the state of a potentially long remote or async operation.

Members Documentation

Property<Status> qi::ProgressNotifier::status

Current status of the operation associated to this notifier. ProgressNotifier::Status

Property<double> qi::ProgressNotifier::progress

Progress state of the operation associated with this notifier. By default you can assume a normalized value ranging between 0.0 (no work is done) to 1.0 (all work is done). The semantic of this value is defined by the operation implementation and could be different from the default but should then be documented.

Function Documentation

qi::ProgressNotifier::~ProgressNotifier()
bool qi::ProgressNotifier::isRunning() const = 0

Brief:

Returns:true if the operation associated to this notifier has started and is neither finished nor canceled nor failed yet, false otherwise.
void qi::ProgressNotifier::_reset() = 0

Reset the status of the algorithm to the idle state with no progress.

void qi::ProgressNotifier::_notifyRunning() = 0

Notify the observers that the operation associated with this notifier is now running.

void qi::ProgressNotifier::_notifyFinished() = 0

Notify the observers that the operation has successfully ended.

void qi::ProgressNotifier::_notifyCancelled() = 0

Notify the observers that the operation has been canceled by the user.

void qi::ProgressNotifier::_notifyFailed() = 0

Notify the observers that the operation has failed.

void qi::ProgressNotifier::_notifyProgressed(double newProgress) = 0

Brief:

Parameters:
  • newProgress – New value representing the total progress of the operation. By default, uses a range from 0.0 (no work has been done yet) to 1.0 (all work is done). The operation implementation is free to use another range if necessary but should clarify the meaning of this value in its documentation.

Notify the observers that the operation progressed.

qi::FileOperation Class Reference

Introduction

More...

#include <qicore/file.hpp>

Public Functions

~FileOperation()
Future<void> start()

Detailed Description

Represent a file operation ready to be executed and expose information about it’s progress state. Exposes the same signals than ProgressNotifier, associated to the operation.

Function Documentation

qi::FileOperation::~FileOperation()
Future<void> qi::FileOperation::start() = 0

Brief:

Returns:A future associated with the operation execution.

Start the associated operation.