Patchwork [1,of,3,V4,RFC] c-hglib: all level 0 function prototypes, provided for context

login
register
mail settings
Submitter Iulian Stana
Date Sept. 1, 2013, 6:43 p.m.
Message ID <301aad54936be170f191.1378061001@doppler>
Download mbox | patch
Permalink /patch/2299/
State Superseded
Headers show

Comments

Iulian Stana - Sept. 1, 2013, 6:43 p.m.
# HG changeset patch
# User Iulian Stana <julian.stana@gmail.com>
# Date 1378056086 -10800
#      Sun Sep 01 20:21:26 2013 +0300
# Node ID 301aad54936be170f1915a034893911f4e742c93
# 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 show how hg_log() is build on the top of
those prototypes.

Patch

diff --git a/client.h b/client.h
new file mode 100644
--- /dev/null
+++ b/client.h
@@ -0,0 +1,218 @@ 
+#ifndef _CLIENT_H_
+#define _CLIENT_H_
+
+#include <errno.h>
+#include <stdint.h>
+#include <sys/types.h>
+
+
+/**
+ * \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;
+	char 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 current header-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.
+ *
+ * \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 current header-action
+ *               (channel, length).
+ * \param protect A protection mechanism.
+ */
+typedef struct hg_handle{
+	pid_t childpid;
+	hg_header next_header;
+	hg_header current_header;
+	int p_read;
+	int p_write;
+	int protect;
+
+	int out_data_size;
+	char *out_data;
+} hg_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 Reading the next channel.
+ *
+ * Before you read or write data, you will want to know for what kind of data is
+ * server waiting, an input data or an output data.
+ * This function will return the current channel for the connection established
+ * by the handle.
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \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)
+ * */
+char hg_next_channel(hg_handle *handle);
+
+/**
+ * \brief Reading the current channel.
+ *
+ * After you finish the reading process you need to know from what channel you
+ * already read your data.
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \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)
+ * */
+char hg_current_channel(hg_handle *handle);
+
+/**
+ * \brief Return the current header.
+ *
+ * Sometimes, the user needs the entire header. This is a way to do that.
+ * \param handle The handle of the connection, wherewith I want to communicate
+ * \retval hg_header  the header stucture for the given handle.
+ * \retval NULL to indicate an error, with errno set appropriately.
+ *
+ * errno can be:
+ *      - EINVAL   - Invalid argument (handle it's set to a null pointer)
+ * */
+hg_header hg_head(hg_handle *handle);
+
+/**
+ * \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