Comments
Patch
new file mode 100644
@@ -0,0 +1,206 @@
+#ifndef _CLIENT_H_
+#define _CLIENT_H_
+
+#include <errno.h>
+#include <stdint.h>
+#include <sys/types.h>
+
+/**
+ * \brief The channel enumeration, contains all the possible channels that
+ * command server could send.
+ **/
+enum channel{
+ o = 'o',
+ e = 'e',
+ r = 'r',
+ I = 'I',
+ L = 'L',
+ wrong_channel
+};
+
+/**
+ * \struct hg_header
+ * \brief This structure contains the variables for the header.
+ *
+ * \var hg_header::channel
+ * The channel will stock a letter that will indicate the type of channel.
+ * \var hg_header::length
+ * The length will stock the size of data that will be send or the maxim data
+ * that can be received by the server.
+ *
+ * \typedef hg_header
+ * \brief This structure contains the variables for the header.
+ *
+ * \param channel
+ * The channel will stock a letter that will indicate the type of channel.
+ * \param length
+ * The length will stock the size of data that will be send or the maxim data
+ * that can be received by the server.
+ * */
+typedef struct hg_header{
+ uint32_t length;
+ enum channel channel;
+} hg_header;
+
+/**
+ * \struct hg_handle
+ * \brief This structure will be use to handle the connection with the server.
+ *
+ * \var hg_handle::p_read Read file description that will read from cmdsrv.
+ * \var hg_handle::p_write Write file description that will write to cmdsrv.
+ * \var hg_handle::header
+ * The header will contain informations about the current header. The
+ * command server will send a new header for each of his actions. This
+ * header will maintain the channel ("o", "e", "r", "I", "L") and through
+ * this channel you will know if the command server will send data or will
+ * wait to receive data.
+ * \var hg_handle::protect
+ * It's a variable that have the purpose to protect calling rawcommand
+ * (new hg command) before calling exitcode function for the last command
+ * \var hg_handle::bytes_on_pipe This field will tell how much data is still on
+ * the pipe
+ * \var hg_handle::out_data_size The size of output data stored in the out_data
+ * pointer.
+ * \var hg_handle::out_data Place where data will be stored.
+ *
+ * \typedef hg_handle
+ * \brief This structure will be use to handle the connection with the server.
+ *
+ * \param "p_read p_write" Contains 2 fd for parent to establis the
+ * bidirectional connection.
+ * \param header The header that will contain the header for the next action
+ * (channel, length).
+ * \param protect A protection mechanism.
+ * \param bytes_on_pipe This field will tell how much data is still in the pipe
+ * \param out_data_size The size of output data stored in the out_data pointer.
+ * \param out_data Place where data will be stored.
+ */
+typedef struct hg_handle{
+ hg_header *header;
+ int bytes_on_pipe;
+ int p_read;
+ int p_write;
+ int protect;
+
+ int out_data_size;
+ char *out_data;
+} hg_handle;
+
+/**
+ * \brief Reading the header from cmdsrv.
+ *
+ * The function will read the header from the command server and will save it to
+ * the header parameter of the handle structure.
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \retval header if succesfull
+ * \retval NULL to indicate an error, with errno set appropriately
+ *
+ * errno can be:
+ * - EINVAL - Invalid argument (handle it's set to a null pointer)
+ * - read(2) command errors
+ * */
+hg_header *hg_read_header(hg_handle *handle);
+
+/**
+ * \brief Open the connection with the mercurial command server.
+ *
+ * The handle structure will be allocated.
+ * \param path The path to the repository wherewith I want to create a connection
+ * NULL argument means the repository in which I am.
+ * \param encoding Will set HGENCODING to the given encoding
+ * NULL argument means the default encoding. (UTF-8)
+ * \retval handle - A handle for this connection.
+ * \retval NULL Indicate an error, with errno set appropriately.
+ *
+ * errno can be :
+ * - execl(2) command errors
+ * - dup2(2) command errors
+ * - fork(2) command errors
+ * - pipe(2) command errors
+ * - EFAULT - for a bad path address
+ * - EINVAL - for a bad encoding
+ * */
+hg_handle *hg_open(const char *path, char *encoding);
+
+/**
+ * \brief Close the connection for the given handle.
+ *
+ * Erase the handle and free the memory
+ * \param handle The handle of the connection that I want to close
+ * \retval 0 if successful
+ * \retval -1 to indicate an error, with errno set appropriately.
+ *
+ * errno can be:
+ * - EINVAL - Invalid argument ( handle it's set to a null pointer)
+ * - kill(2) command errors
+ * */
+int hg_close(hg_handle **handle);
+
+/**
+ * \brief Sending a command to the mercurial command server, through the given
+ * handle.
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \param command An array of pointers to null-terminated strings that represent
+ * the argument list available to the new command. The list of
+ * arguments must be terminated by a NULL pointer.
+ * \retval 0 if successful
+ * \retval -1 to indicate an error, with errno set appropriately.
+ *
+ * errno can be:
+ * - EINVAL - Invalid argument ( handle it's set to a null pointer)
+ * - write(2) command errors
+ * */
+int hg_rawcommand(hg_handle *handle, char *const command[]);
+
+/**
+ * \brief Reading some unparse data from the server.
+ *
+ * Will read just a 'line', the header that is received from server and the
+ * data that comes after the header
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \param buffer A character array where the read content will be stored.
+ * \param sizebuff The number of bytes to read.
+ * \retval Number the number of bytes that were read.
+ * \retval -1 to indicate an error, with errno set appropriately.
+ *
+ * errno can be:
+ * - EINVAL - Invalid argument (handle it's set to a null pointer)
+ * - read(2) command errors
+ * */
+int hg_rawread(hg_handle *handle, char *buffer, size_t sizebuff);
+
+/**
+ * \brief Will write the buffer to server for the connection establish by the
+ * handle.
+ *
+ * This function will be used when one of the input channels will be received
+ * from the command server. ('I' or 'L' channels)
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \param buffer A null terminated character string of the content to write.
+ * \param sizebuff The number of bytes to write
+ * \retval Number the number of bytes that were written
+ * \retval -1 to indicate an error, with errno set appropriately.
+ *
+ * errno can be:
+ * - EINVAL - Invalid argument (handle it's set to a null pointer)
+ * - write(2) command errors
+ * */
+int hg_rawwrite(hg_handle *handle, const char *buffer, size_t sizebuff);
+
+/**
+ * \brief The exitcode for the current command.
+ *
+ * The server tell use that he finished his action when the 'r' channel is send.
+ * This function will get the exitcode from the server, in as a measure to tell
+ * that the command was finished.
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \retval exitcode if successful
+ * \retval -1 to indicate an error, with errno set appropriately.
+ *
+ * errno can be:
+ * - EINVAL - Invalid argument (handle it's set to a null pointer)
+ * - read(2) command errors
+ * */
+int hg_exitcode(hg_handle *handle);
+
+#endif