request.h

Go to the documentation of this file.

//////////////////////////////////////////////////////////////
///
/// \file request.h
/// This file Defines everything related to handling Requests
///
/// //////////////////////////////////////////////////////////
#ifndef REQUEST_H
#define REQUEST_H
 
#include <SNF/SNF.h>
#include <SNF/clt.h>
#include <SNF/utility.h>
#include <SNF/opcode.h>
#include <SNF/network.h>
 
/// @brief Requests's Default Request ID
/// @note Server Requests to client always must have this as their ID 
#define NULLREQUEST "000000000000000"
/// @brief Defines the Requests' maximum length
#define SNF_REQUEST_MAXSIZE 4096
 
/// @brief Shortened definition of struct SNF_Request_t .
typedef struct SNF_Request_t SNF_RQST;
/// @brief Shortened definition of struct SNF_Request_args_t .
typedef struct SNF_Request_args_t SNF_RQST_ARG;
 
/// @brief The Structure for saving Requests
struct SNF_Request_t
{
    /// @brief Defines the UID Saved
    /// @note You must take in mind that
    ///    * In Case the SNF_RQST came from a client
    ///         * The UID represents the Request's ID
    ///    * In Case the SNF_RQST is generated by the server 
    ///         * In Case you want to reply to a SNF_RQST ,the generates reponse's UID must be the same as the Client Request's UID.
    ///             * use \ref snf_request_gen_response
    ///         * In Case you want to send a server request, then the request's UID must be equal to \ref NULLREQUEST 
    ///             * use \ref snf_request_gen_server_OPCODE (Although you cant put any arguments)
    ///             * use \ref snf_request_gen_response ( \ref snf_request_gen_wUID ( \ref NULLREQUEST ), Your OPCODE, Your ARGUMENTS);
    char UID[16];
    /// @brief Defines The OPCODE of the request
    SNF_opcode *OPCODE;
    /// @brief Defines the arguments inside the Request
    SNF_RQST_ARG *args;
};
 
struct SNF_Request_args_t
{
    /// @brief The Argument's Content
    char *arg;
    /// @brief The next argument
    SNF_RQST_ARG *next;
};
 
/// @brief Frees a SNF_RQST *
/// @param Request Pointer to be free'd
extern void snf_request_free(SNF_RQST *Request);
/// @brief Generates a new empty request
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST instance
extern SNF_RQST *snf_request_gen();
/// @brief Generates a new empty request that has an UID
/// @param UID The new Request's UID
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST instance
extern SNF_RQST *snf_request_gen_wUID(const char UID[16]);
/// @brief Generates a new response request
/// @param Original The request to reply to
/// @param OPCODE Thre response's OPCODE
/// @param Args The response's arguments
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST instance
/// @note The response Request's UID will match the <strong>Original</strong>'s UID, See \ref SNF_RQST::UID
extern SNF_RQST *snf_request_gen_response(SNF_RQST *Original, SNF_opcode *OPCODE, SNF_RQST_ARG *Args);
/// @brief Generates a server request
/// @param OPCODE server request's OPCODE
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST instance
extern SNF_RQST *snf_request_gen_server_OPCODE(SNF_opcode *OPCODE);
/// @brief Generates a response request using base OPCode 
/// @param Original The request to respond to
/// @param Command Base Command
/// @param Detail Base Command's Detail
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST instance
extern SNF_RQST *snf_request_gen_base(SNF_RQST *Original, SNF_opcode_mmbr_t Command, SNF_opcode_mmbr_t Detail);
/// @brief Generates a response request using undetailed base OPCode 
/// @param Original The request to respond to
/// @param Command Base Command
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST instance
extern SNF_RQST *snf_request_genu_base(SNF_RQST *Original, SNF_opcode_mmbr_t Command);
/// @brief Gets the amount of arguments a request has
/// @param args The request to get it's arguments
/// @return The possible results :
///         * **0** if any of the args were empty 
///         * **int** Amount of \ref SNF_RQST_ARG
extern int snf_request_get_nargs(SNF_RQST *args);
 
/// @brief Generates a new Argumment 
/// @param arg Argument's Content
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST_ARG instance
extern SNF_RQST_ARG *snf_request_arg_gen(const char *arg);
/// @brief Frees an instance of \ref SNF_RQST_ARG
/// @param arg Instance to be free'd
/// @warning Do not free an argumment if \ref SNF_RQST_ARG::next contains a pointer, and it could cause a memoery leak<br>
///         * If you wish to free all arguments then use \ref snf_request_args_free
///         * If you wish to free just that one argument then save the \ref SNF_RQST_ARG::next in a variable, replace the **arg** instance with the the latter variable, and then free **arg**
extern void snf_request_arg_free(SNF_RQST_ARG *arg);
/// @brief Frees all instance of \ref SNF_RQST_ARG that were linked together using \ref SNF_RQST_ARG::next
/// @param arg arg Instances to be free'd
extern void snf_request_args_free(SNF_RQST_ARG *arg);
// Only use on first time. unless you dont care about execution time
 
/// @brief Inserts an arguments to the end of **Request**'s \ref SNF_RQST_ARG List
/// @param Request Request to be operated on
/// @param arg Argument to be added
/// @note If you want to Insert a bunch of instances of \ref SNF_RQST_ARG then preferably avoid calling this function
///     but instead crteate the  first instance in *head* variable( \ref SNF_RQST_ARG ) and also put it in a *pointer*( \ref SNF_RQST_ARG ) variable
///     ( at first it's value *Must* be the same as the *head* variable ) variable then everytime you create a new argument 
///     you save it in the \ref SNF_RQST_ARG::next member of the *pointer* variable, and then assign the \ref SNF_RQST_ARG::next 's new value as the *pointer*
///     variable, at the end, use this function only the *head* variable
extern void snf_request_arg_insert(SNF_RQST *Request, SNF_RQST_ARG *arg);
/// @brief Fetches the request from the incoming Client
/// @param Client Client to receive request from.
/// @return The possible results :
///         * **NULL** if there was an error with calloc ( See errno and calloc's errcodes )
///         * **Pointer** to the \ref SNF_RQST instance
extern SNF_RQST *snf_request_fetch(SNF_CLT *Client);
 
/// @brief Send a request to a Client
/// @param Client Receiving Client
/// @param Request Request to Send
extern void snf_request_send(SNF_CLT *Client, SNF_RQST *Request);
/// @brief Sends a confirmation Response request to the client
/// @param Client Receiving Client
/// @param Original Client's Original Request
extern void snf_request_send_confirm(SNF_CLT *Client, SNF_RQST *Original);
/// @brief Sends a rejection Response request to the client
/// @param Client Receiving Client
/// @param Original Client's Original Request
extern void snf_request_send_reject(SNF_CLT *Client, SNF_RQST *Original);
/// @brief Sends a invalidation Response request to the client
/// @param Client Receiving Client
/// @param Original Client's Original Request
extern void snf_request_send_invalid(SNF_CLT *Client, SNF_RQST *Original);
 
#endif