Patchwork [01,of,55,RFC,c-hglib:level1] c-hglib: all level 0 function prototypes, provided for context

login
register
mail settings
Submitter Iulian Stana
Date Sept. 14, 2013, 12:35 a.m.
Message ID <02484cf0647286223358.1379118913@doppler>
Download mbox | patch
Permalink /patch/2445/
State Deferred, archived
Headers show

Comments

Iulian Stana - Sept. 14, 2013, 12:35 a.m.
# HG changeset patch
# User Iulian Stana <julian.stana@gmail.com>
# Date 1379107076 -10800
#      Sat Sep 14 00:17:56 2013 +0300
# Node ID 02484cf0647286223358d7ec6df194d704f02c47
# Parent  0000000000000000000000000000000000000000
c-hglib: all level 0 function prototypes, provided for context

I am putting in this commit the level 0 prototypes, that I already showed you in
other patchbomb, with the purpose to give you the entire code and to give you
the possibility to build the level 1 from this patchbomb.

Patch

diff --git a/client.h b/client.h
new file mode 100644
--- /dev/null
+++ b/client.h
@@ -0,0 +1,216 @@ 
+#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::childpid 
+ *      The pid of the process that will open the connection with cmdsrv.
+ * \var hg_handle::header 
+ *      The header that will contain the header for the next action
+ *      (channel, length).
+ *      Through this header, the user will know on what channel the server will
+ *      send his data.
+ * \var hg_handle::protect
+ *      Create a protection mechanism to block calling rawcommand(new hg
+ *      command) until the exitcode for the last command is not received.
+ * \var hg_handle::bytes_on_pipe This field will tell how much data is still in
+ *                               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 for the bidirectional 
+ *                         connection.
+ * \param childpid The pid of the process that will open the 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{
+	pid_t childpid;
+	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);
+
+/**
+ * \brief Getting the output data, received from the last command.
+ *
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \retval string Indicate the output data.
+ **/
+char *get_output_data(hg_handle *handle);
+
+#endif
diff --git a/utils.h b/utils.h
new file mode 100644
--- /dev/null
+++ b/utils.h
@@ -0,0 +1,32 @@ 
+#ifndef _UTILS_CHG_H_
+#define _UTILS_CHG_H_
+
+#include <stdint.h>
+
+/** 
+ * \brief Byte swap unsigned int
+ * \param val an uint32_t integer
+ * \retval uint32_t the bigendian form of val value
+ * */
+uint32_t swap_uint32( uint32_t val );
+
+/**
+ * \brief Prepare the command for sending process. 
+ * 
+ * Replace all the blank space with the '\0' character.
+ * \param command an array that will contain the mercurial command
+ * \param cmd_size - array size
+ * \retval string representing the command that will be send to cmdsrv
+ * \retval *cmd_size will be set on string size
+ * 
+ * \code
+ *    char *command[] = {"tip", "-p", NULL};
+ *    char *cmd_str = cmd_prepare(command, 0);
+ *    prinf("==%s==", cmd_str);
+ *    ---> ==tip\0-p==
+ * \endcode
+ * */
+char *cmd_prepare(char *const command[], int *cmd_size);
+
+
+#endif