From patchwork Tue Sep 17 19:48:05 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: hglib: client header file, level 0 prototypes From: Iulian Stana X-Patchwork-Id: 2511 Message-Id: <0939f135beefc5755be7.1379447285@doppler> To: mercurial-devel@selenic.com Date: Tue, 17 Sep 2013 22:48:05 +0300 # HG changeset patch # User Iulian Stana # Date 1379445096 -10800 # Tue Sep 17 22:11:36 2013 +0300 # Node ID 0939f135beefc5755be7ba9d7dab1253c0877b0d # Parent 0000000000000000000000000000000000000000 hglib: client header file, level 0 prototypes Level 0: raw level. This level represents the lowest level of 'hglib' API. The purpose of this level is to pass a raw command string and to get some unparsed results. The header file contains the basic functions that will be use in the hglib API. Those functions, give the possibility to establish a connection with the mercurial command server, and the possibility to exchange messages. diff --git a/hglib/client.h b/hglib/client.h new file mode 100644 --- /dev/null +++ b/hglib/client.h @@ -0,0 +1,206 @@ +#ifndef _CLIENT_H_ +#define _CLIENT_H_ + +#include +#include +#include + +/** + * \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