libdoclone  0.7.0
Classes | Typedefs | Enumerations | Functions
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.
dc_doclonedoclone_new ()
 Creates a new dc_doclone object in the heap and returns its address.
void doclone_destroy (dc_doclone *dc_obj)
 Destroy the given dc_doclone object.
int doclone_create (const dc_doclone *dc_obj)
 Creates an image of a device.
int doclone_restore (const dc_doclone *dc_obj)
 Restores an image in a device.
int doclone_send (const dc_doclone *dc_obj)
 Sends an image or a device to the network.
int doclone_receive (const dc_doclone *dc_obj)
 Receives an image or a device from the network.
int doclone_chain_origin (const dc_doclone *dc_obj)
 Sends an image or a device to the network in link mode.
int doclone_chain_link (const dc_doclone *dc_obj)
 Receives an image or a device from the network in link mode.
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_nodes_number (dc_doclone *dc_obj, unsigned int number)
 Sets the number of receivers of the given dc_doclone object.
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:

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:

Subscribing to any of these events can be performed by calling one of the following functions:

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);

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

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:

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.

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.

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.

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])