C wrapper API

C API for libdoclone. More...

Classes
struct	dc_doclone
	Main object of the C wrapper API of libdoclone. More...

Typedefs
typedef enum dcTransferEvent	dcTransferEvent
typedef enum dcOperationEvent	dcOperationEvent
typedef enum dcOperationType	dcOperationType
typedef enum dcEvent	dcEvent
typedef void(*	transferCallback )(dcTransferEvent event, uint64_t numBytes)
	The prototype of the function to be called when a transfer event has occurred.
typedef void(*	operationCallback )(dcOperationEvent event, dcOperationType type, const char *target)
	The prototype of the function to be called when an operation event has occurred.
typedef void(*	generalCallback )(dcEvent event, const char *target)
	The prototype of the function to be called when a general event has occurred.
typedef void(*	notificationCallback )(const char *str)
	The prototype of the function to be called when an exception occurs and notifies its message.
typedef struct dc_doclone	dc_doclone

Enumerations
enum	dcTransferEvent { TRANS_TOTAL_SIZE, TRANS_TRANSFERRED_BYTES }
	C wrapper for Doclone::dcTransferEvent. More...
enum	dcOperationEvent { OPER_ADD, OPER_MARK_COMPLETED }
	C wrapper for Doclone::dcOperationEvent. More...
enum	dcOperationType {   OP_NONE, OP_READ_PARTITION_TABLE, OP_MAKE_DISKLABEL, OP_CREATE_PARTITION,   OP_FORMAT_PARTITION, OP_WRITE_PARTITION_FLAGS, OP_WRITE_FS_LABEL, OP_WRITE_FS_UUID,   OP_READ_DATA, OP_WRITE_DATA, OP_GRUB_INSTALL, OP_TRANSFER_DATA,   OP_WAIT_SERVER, OP_WAIT_CLIENTS }
	C wrapper for Doclone::dcOperationType. More...
enum	dcEvent { EVT_CANCEL_EXECUTION, EVT_FINISH_EXECUTION, EVT_NEW_CONNECION }
	C wrapper for Doclone::dcEvent. More...

Functions
int	libdoclone_is_present (void)
	For compatibility with AC_CHECK_LIB. More...
dc_doclone *	doclone_new ()
	Creates a new dc_doclone object in the heap and returns its address. More...
void	doclone_destroy (dc_doclone *dc_obj)
	Destroy the given dc_doclone object. More...
int	doclone_create (const dc_doclone *dc_obj)
	Creates an image of a device. More...
int	doclone_restore (const dc_doclone *dc_obj)
	Restores an image in a device. More...
int	doclone_send (const dc_doclone *dc_obj)
	Sends an image or a device to the network. More...
int	doclone_receive (const dc_doclone *dc_obj)
	Receives an image or a device from the network. More...
int	doclone_chain_origin (const dc_doclone *dc_obj)
	Sends an image or a device to the network in link mode. More...
int	doclone_chain_link (const dc_doclone *dc_obj)
	Receives an image or a device from the network in link mode. More...
void	doclone_set_image (dc_doclone *dc_obj, const char *image)
	Sets the image path of the given dc_doclone object.
void	doclone_set_device (dc_doclone *dc_obj, const char *device)
	Sets the device path of the given dc_doclone object.
void	doclone_set_address (dc_doclone *dc_obj, const char *address)
	Sets the IP address of the server for the given dc_doclone object.
void	doclone_set_interface (dc_doclone *dc_obj, const char *interface)
	Sets the IP address of the interface to be used in the link mode.
void	doclone_set_nodes_number (dc_doclone *dc_obj, unsigned int number)
	Sets the number of receivers of the given dc_doclone object. More...
void	doclone_set_empty (dc_doclone *dc_obj, unsigned short empty)
	Sets the empty flag of the given dc_doclone object.
void	doclone_set_force (dc_doclone *dc_obj, unsigned short force)
	Sets the force flag of the given dc_doclone object.
void	doclone_subscribe_to_tranfer_events (dc_doclone *dc_obj, transferCallback call)
	Through this function the user can set its callback for the transfer events of the library.
void	doclone_subscribe_to_operation_events (dc_doclone *dc_obj, operationCallback call)
	Through this function the user can set its callback for the operation events of the library.
void	doclone_subscribe_to_general_events (dc_doclone *dc_obj, generalCallback call)
	Through this function the user can set its callback for the general events of the library.
void	doclone_subscribe_to_notifications (dc_doclone *dc_obj, notificationCallback call)
	Through this function the user can set its callback for listen the notifications of the exceptions.

Detailed Description

C API for libdoclone.

The main type of the C API is the dc_doclone struct. This struct provides a way for calling the methods of libdoclone from a C program. To create an object, the function doclone_new() must be called by this way:

dc_doclone *dc_obj = doclone_new();

After using a dc_doclone object, its memory can be freed by calling:

doclone_destroy(dc_obj);

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 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 calling one of the following functions:

doclone_subscribe_to_tranfer_events(dc_doclone *dc_obj, transferCallback call);
doclone_subscribe_to_operation_events(dc_doclone *dc_obj, operationCallback call);
doclone_subscribe_to_general_events(dc_doclone *dc_obj, generalCallback call);
doclone_subscribe_to_notifications(dc_doclone *dc_obj, notificationCallback call);

All these functions receive a pointer to the dc_doclone object as first parameter, and a pointer to a callback function as second. The callback function passed as parameter must have the proper prototype. These prototypes are specified by some defined types:

transferCallback:  void (*transferCallback) (dcTransferEvent event, uint64_t numBytes);

operationCallback: void (*operationCallback) (dcOperationEvent event, dcOperationType type, const char *target);

generalCallback: void (*generalCallback) (dcEvent event, const char *target);

notificationCallback void (*notificationCallback) (const char *str);

Note that dcTransferEvent, dcOperationEvent, dcOperationType and dcEvent are just a C wrapper for Doclone::dcTransferEvent, Doclone::dcOperationEvent, Doclone::dcOperationType and Doclone::dcEvent enums of the library.

After declaring one function with the proper prototype, it is possible to use it as callback to listen the library events, for example:

void notify(const char *str) {
    dprintf(2, "%s\n", str);
}

...

doclone_subscribe_to_notifications(dc_obj, &notify);

By this way it can listen to all the events of the library:

doclone_subscribe_to_tranfer_events(dc_obj, &notifyTransfer);
doclone_subscribe_to_operation_events(dc_obj, &notifyOperation);
doclone_subscribe_to_general_events(dc_obj, &notifyGeneral);
doclone_subscribe_to_notifications(dc_obj, &notify);

The next step is to set all the dc_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 functions for configuring those properties:

void doclone_set_image(dc_doclone *dc_obj, const char *image);
void doclone_set_device(dc_doclone *dc_obj, const char *device);
void doclone_set_address(dc_doclone *dc_obj, const char *address);
void doclone_set_nodes_number(dc_doclone *dc_obj, unsigned int number);
void doclone_set_empty(dc_doclone *dc_obj, unsigned short empty);
void doclone_set_force(dc_doclone *dc_obj, unsigned short force);

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

int doclone_create(const dc_doclone *dc_obj);
int doclone_restore(const dc_doclone *dc_obj);
int doclone_send(const dc_doclone *dc_obj);
int doclone_receive(const dc_doclone *dc_obj);
int doclone_chain_origin(const dc_doclone *dc_obj);
int doclone_chain_link(const dc_doclone *dc_obj);

All of these functions receive a pointer to a dc_doclone object which attributes must be properly set, and return 0 if everything is OK, or -1 if something has failed.

These are some examples of use:

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

    doclone_set_image(dc_obj, "/home/user/image.doclone");
    doclone_set_device(dc_obj, "/dev/sdb");

  • Then call the create function:

    doclone_create(dc_obj);

  • Or the restore function:

    doclone_restore(dc_obj);

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

    doclone_set_nodes_number(dc_obj, 1);
    doclone_set_image(dc_obj, "/home/user/image.doclone");

  • Then call the send function:

    doclone_send(dc_obj);

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

    doclone_set_address(dc_obj, "192.168.0.10");
    doclone_set_device(dc_obj, "/dev/sdb");
    
    doclone_receive(dc_obj);

Enumeration Type Documentation

enum dcEvent

C wrapper for Doclone::dcEvent.

Enumerator
EVT_CANCEL_EXECUTION	The program detects a SIGINT.
EVT_FINISH_EXECUTION	Execution successfully finished.
EVT_NEW_CONNECION	New incoming connection.

enum dcOperationEvent

C wrapper for Doclone::dcOperationEvent.

Enumerator
OPER_ADD	The subject has added a new operation pending.
OPER_MARK_COMPLETED	The subject has completed an operation pending.

enum dcOperationType

C wrapper for Doclone::dcOperationType.

Enumerator
OP_NONE	No operation.
OP_READ_PARTITION_TABLE	Reading the partition table.
OP_MAKE_DISKLABEL	Writing a new disklabel.
OP_CREATE_PARTITION	Creating a new partition.
OP_FORMAT_PARTITION	Formatting a partition.
OP_WRITE_PARTITION_FLAGS	Writing the flags of a partition.
OP_WRITE_FS_LABEL	Writing the label of a filesystem.
OP_WRITE_FS_UUID	Writing the uuid of a filesystem.
OP_READ_DATA	Reading the data of a partition.
OP_WRITE_DATA	Writing the data of a partition.
OP_GRUB_INSTALL	Installing GRUB.
OP_TRANSFER_DATA	Sending or receiving data.
OP_WAIT_SERVER	Waiting for connect to server.
OP_WAIT_CLIENTS	Waiting for connect to client/s.

enum dcTransferEvent

C wrapper for Doclone::dcTransferEvent.

Enumerator
TRANS_TOTAL_SIZE	The value of the total size to be transferred has changed.
TRANS_TRANSFERRED_BYTES	The value of the transferred bytes has changed.

Function Documentation

int doclone_chain_link

(

const dc_doclone *

dc_obj

)

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

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

Returns

0 if the process has success, -1 if any error happen

int doclone_chain_origin

(

const dc_doclone *

dc_obj

)

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

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

Returns

0 if the process has success, -1 if any error happen

int doclone_create

(

const dc_doclone *

dc_obj

)

Creates an image of a device.

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

Returns

0 if the process has success, -1 if any error happen

void doclone_destroy

(

dc_doclone *

dc_obj

)

Destroy the given dc_doclone object.

If this function is not called, the object will never be freed

dc_doclone * doclone_new

(

)

Creates a new dc_doclone object in the heap and returns its address.

Returns

Pointer to the newly dc_doclone object

int doclone_receive

(

const dc_doclone *

dc_obj

)

Receives an image or a device from the network.

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

Returns

0 if the process has success, -1 if any error happen

int doclone_restore

(

const dc_doclone *

dc_obj

)

Restores an image in a device.

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

Returns

0 if the process has success, -1 if any error happen

int doclone_send

(

const dc_doclone *

dc_obj

)

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.

Returns

0 if the process has success, -1 if any error happen

void doclone_set_nodes_number	(	dc_doclone *	dc_obj,
		unsigned int	number
	)

Sets the number of receivers of the given dc_doclone object.

Useful only if this object will be used to be a server

int libdoclone_is_present

(

void

)

For compatibility with AC_CHECK_LIB.

In configure.ac, the user of the library can check if libdoclone is installed by either calling the PKG_CHECK_MODULES macro or calling AC_CHECK_LIB macro by this way: AC_CHECK_LIB([doclone], [libdoclone_is_present], [action-if-found], [action-if-not-found])