C++ API

C++ API for libdoclone. More...

Functions
static Clone *	Doclone::Clone::getInstance ()
	Returns a pointer to a Doclone::Clone object. More...
void	Doclone::Clone::create () throw (Exception)
	Creates an image of a device. More...
void	Doclone::Clone::restore () throw (Exception)
	Restores an image in a device. More...
void	Doclone::Clone::send () throw (Exception)
	Sends an image or a device to the network. More...
void	Doclone::Clone::receive () throw (Exception)
	Receives an image or a device to the network. More...
void	Doclone::Clone::chainOrigin () throw (Exception)
	Sends an image or a device to the network in link mode. More...
void	Doclone::Clone::chainLink () throw (Exception)
	Receives an image or a device to the network in link mode. More...
void	Doclone::Clone::setEmpty (bool empty)
	Sets the no-data mode on/off.
void	Doclone::Clone::setNodesNumber (unsigned int nodesNum)
	Sets the number of receivers in the network. More...
void	Doclone::Clone::setDevice (const std::string &device)
	Sets the device on which work. More...
void	Doclone::Clone::setImage (const std::string &image)
	Sets the image on which work. More...
void	Doclone::Clone::setAddress (const std::string &address)
	Sets the IP address of the server in unicast/multicast mode. More...
void	Doclone::Clone::setInterface (const std::string &interface)
	Sets the IP address of the network interface to be used in the link mode. More...
void	Doclone::Clone::setForce (bool force)
	Sets the force mode on/off. More...

Detailed Description

C++ API for libdoclone.

This class provides a way for calling the methods of libdoclone from a C++ program. To create an object, the static method getInstance() must be called by this way:

Doclone::Clone *dcl = Doclone::Clone::getInstance();

It is possible to subscribe the events of the library. These can be used to know the operations progress and possible incidences. To do this, some functions must be implemented with the proper prototype.

First of all, These are the four kinds of libdoclone events:

• The transfer events: Events that inform about the process of data read/write or send/receive. There are only two transfer events: The TRANSFERRED_BYTES event and the TOTAL_SIZE event.
  • The TRANSFERRED_BYTES can be raised several times during the program execution, and informs about the amount of bytes transferred until now.
  • The TOTAL_SIZE is raised only once in the execution time, when the library has determined the total amount of bytes that should be transferred. This can be useful for creating a progress bar.
• The operation events: One operation is one action that the library will perform. There are many different operations, such as reading partition table of a disc, writing the UUID of a file system, installing GRUB, etc. This kind of event can have two states: Pending or Completed. The library can add new pending operations and mark them as completed many times during the execution time.
• The general events: These are simple events that can happen during the program execution, such as receiving a connection from other libdoclone instance or interrupting the program by order of the user.
• The notification of the exceptions: In case of something doesn't work as expected, for example, when the library tries to write in a folder which access is denied or in case of connection error, then the library raises an exception until the highest level of the calling hierarchy. Since C doesn't support exceptions, all of them are captured by the library, but their error messages are sent to the listening views.

Subscribing to any of these events can be performed by extending the Doclone::AbstractObserver class and overriding all its notify() methods:

void notify(Doclone::dcTransferEvent event, uint64_t numBytes);
void notify(Doclone::dcOperationEvent event,
    Doclone::dcOperationType type, const std::string &target);
void notify(Doclone::dcEvent event, const std::string &target);
void notify(const std::string &str);

For example:

class MyObserver : public Doclone::AbstractObserver {
public:
    MyObserver();

    void notify(Doclone::dcTransferEvent event, uint64_t numBytes);
    void notify(Doclone::dcOperationEvent event,
            Doclone::dcOperationType type, const std::string &target);
    void notify(Doclone::dcEvent event, const std::string &target);
    void notify(const std::string &str);
};

void MyObserver::notify(const std::string &str) {
    std::cerr << "Something has happened:" << " " << str << std::endl;
}

The next step is to set all the doclone object required properties before performing the work. These are:

• image (char*): It is the image file path to work with
• device (char*): The device path to be read or written
• address (char*): The server IP address
• nodes number (int): The number of receivers
• empty (int): Clone the partition table without reading/writing the data (true or false)
• force (int): Force working even if the image doesn't fit in the destination device (true or false)

These are some setters for configuring the properties:

void setEmpty(bool empty);
void setNodesNumber(unsigned int nodesNum);
void setDevice(const std::string &device);
void setImage(const std::string &image);
void setAddress(const std::string &address);
void setForce(bool force);

The last step is to call one of the methods that perform the work:

void create() throw(Exception);
void restore() throw(Exception);
void send() throw(Exception);
void receive() throw(Exception);
void chainOrigin() throw(Exception);
void chainLink() throw(Exception);

All this methods raise an exception if anything goes wrong. The library has two kinds of exceptions, the Warning Exceptions and the Error Exceptions. The Warning Exceptions don't stop the execution and are captured in the library, but their messages are sent to the views. These messages are received by the views with "void notify(const std::string &str)" method override. The Error Exceptions are defined for severe errors, these ones always stop the execution and are raised to the caller. The library user must decide what to do with them.

These are some examples of use:

• Creating or restoring an image of/into a device:
  • Set the image and the device on the doclone object:

    Doclone::Clone *dcl = Doclone::Clone::getInstace();
    
    dcl->setImage("/home/user/image.doclone");
    dcl->setDevice("/dev/sdf");

  • Then call the create function:

    try {
        dcl->create();
    } catch (const Doclone::Exception &ex) {
        // Do something
    }

  • Or call the restore function:

    try {
        dcl->restore();
    } catch (const Doclone::Exception &ex) {
        // Do something
    }

• Sending an image over network:
  • For the server, set the number of receivers and the image to read.

    dcl->setNodesNumber(1);
    dcl->setImage("/home/user/image.doclone");

  • Then call the send function:

    try {
        dcl->send();
    } catch (const Doclone::Exception &ex) {
        // Do something
    }

  • For the client, set the server IP address and the device to write:

    dcl->setAddress("192.168.0.10");
    dcl->setDevice("/dev/sdb");
    
    try {
        dcl->receive();
    } catch (const Doclone::Exception &ex) {
        // Do something
    }

Function Documentation

void Doclone::Clone::chainLink	(		)
throw	(	Exception
	)

Receives an image or a device to the network in link mode.

Image or device path must be set before calling this function.

void Doclone::Clone::chainOrigin	(		)
throw	(	Exception
	)

Sends an image or a device to the network in link mode.

Image or device path must be set before calling this function.

void Doclone::Clone::create	(		)
throw	(	Exception
	)

Creates an image of a device.

Both image an device path must be set before calling this function.

Clone * Doclone::Clone::getInstance ( )

static

Returns a pointer to a Doclone::Clone object.

Returns

A pointer to a doclone object

void Doclone::Clone::receive	(		)
throw	(	Exception
	)

Receives an image or a device to the network.

Server's IP and either image or device path must be set before calling this function.

void Doclone::Clone::restore	(		)
throw	(	Exception
	)

Restores an image in a device.

Both image an device path must be set before calling this function.

void Doclone::Clone::send	(		)
throw	(	Exception
	)

Sends an image or a device to the network.

The number of receivers and either image or device path must be set before calling this function.

void Doclone::Clone::setAddress

(

const std::string &

address

)

Sets the IP address of the server in unicast/multicast mode.

Parameters

address

IP Address

void Doclone::Clone::setDevice

(

const std::string &

device

)

Sets the device on which work.

Parameters

device

Device path

void Doclone::Clone::setForce

(

bool

force

)

Sets the force mode on/off.

Parameters

force

true = on; false = off

void Doclone::Clone::setImage

(

const std::string &

image

)

Sets the image on which work.

Parameters

image

Image path

void Doclone::Clone::setInterface

(

const std::string &

interface

)

Sets the IP address of the network interface to be used in the link mode.

Parameters

interface

IP Address of the interface

void Doclone::Clone::setNodesNumber

(

unsigned int

nodesNumber

)

Sets the number of receivers in the network.

Parameters

nodesNumber

Number of nodes