Patchwork hglib: client header file, level 0 prototypes

login
register
mail settings
Submitter Iulian Stana
Date Sept. 17, 2013, 7:48 p.m.
Message ID <0939f135beefc5755be7.1379447285@doppler>
Download mbox | patch
Permalink /patch/2511/
State Deferred, archived
Headers show

Comments

Iulian Stana - Sept. 17, 2013, 7:48 p.m.
# HG changeset patch
# User Iulian Stana <julian.stana@gmail.com>
# 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.
Matt Mackall - Sept. 17, 2013, 11:20 p.m.
On Tue, 2013-09-17 at 22:48 +0300, Iulian Stana wrote:
> # HG changeset patch
> # User Iulian Stana <julian.stana@gmail.com>
> # Date 1379445096 -10800
> #      Tue Sep 17 22:11:36 2013 +0300
> # Node ID 0939f135beefc5755be7ba9d7dab1253c0877b0d
> # Parent  0000000000000000000000000000000000000000
> hglib: client header file, level 0 prototypes

I've queued this to a repo that will shortly be pushed to:

https://bitbucket.org/mpmselenic/c-hglib

(which I may give other reviewers access to as the need arises)

Two notes:

- I've fixed up some things check-code spotted, namely long lines and
trailing whitespace 
- it's going to be very silly to prefix all of these patches with hglib,
pick a more specific keyword

I've just pushed a couple check-code changes so it now checks *.h files.

Patch

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