SNF's Requests

Table of Contents

• About Requests
• Generating a Request
  • A Response Request (Standard)
  • A Response Request (Using Base OPCode)
  • A Custom Request
• Generating Arguments
• Adding Arguments
  • For Requests generated using the "Standard Method"
  • For requests generated without the "Standard Method"
  • For multiple arguments
• Sending Requests
• Freeing Requests

◄ Previous: SNF's OPCodes

About Requests

Request are like the packages that would be transferred back and forth between client and server

Generating a Request

Generating Request depends on either it's as a response request, or as a server request to the client, See SNF_Request_t::UID for more detail about the difference.

A Response Request (Standard)

a standard way under normal cicumstances requires 3 things

1. Client's Original Request (See  Add a command )
2. The Response's OPCode ( See Generate OPCodes )
3. The Response's argument.

Note

1. Arguments could be NULL
2. For more about generating arguments that go along with the Request Check this

and then we'll call snf_request_gen_response

Warning

for the sake for simplicity, no error handling was included in the example

Example We want to write the respondtoclient function defined in  Add a command

SNF_RQST * respondtoclient(SNF_RQST * Request)
{
    // Generate your Request's Response OPCode 
    SNF_opcode *op = snf_opcode_get(..);
 
    // Generate your Request's Argument ( Assuming we only have one argument)
    // Remember that Content Must be a string for this version
    SNF_RQST_ARG * arg = snf_request_arg_gen("<Argument Content>");
 
 
    SNF_RQST *ServerResponse = snf_request_gen_response(
        Request, // Client's Original Request
        op, // Your Request's OPCode
        arg // Your Request's Content
    );
    /*
        Do Whatever you want to do with Server Response
    */
 
    return ServerResponse;
}

A Response Request (Using Base OPCode)

Instead of using the Standard function for creating a response request you could create a request using another method that requires 3 things

1. Client's Original Request (See  Add a command )
2. The Base Command's defining byte
3. The Base Command Detail's defining byte

Note

As for aguments follow Generating Arguments

and then we'll call snf_request_gen_base (Or snf_request_genu_base if you don't want the set a detail )

Warning

for the sake for simplicity, no error handling was included in the example

Example We want to write the respondtoclient function defined in  Add a command

SNF_RQST * respondtoclient(SNF_RQST * Request)
{
    SNF_RQST *ServerResponse = snf_request_gen_base(
        Request, // Client's Original Request
        0xFF, // Base Command
        0x01 // Base Detail
    );
    // Or for undetailed base OPCode 
    // SNF_RQST *ServerResponse = snf_request_genu_base(
    //     Request, // Client's Original Request
    //     0xFF // Base Command
    // );
    /*
        Do Whatever you want to do with Server Response
    */
    return ServerResponse;
}

A Custom Request

Assuming you want to sent a request to a client (eg: Broadcasting a message or a Server Event) then we can formulate a Custom Request using: UID will equal NULLREQUEST

• snf_request_gen_server_OPCODE

  // Generate your Request's OPCode 
  SNF_opcode *op = snf_opcode_get(..);
   
  // Generate your Request's Argument ( Assuming we only have one argument)
  // Remember that Content Must be a string for this version
  SNF_RQST_ARG * arg = snf_request_arg_gen("<Argument Content>");
   
  SNF_RQST *ServerRequest = snf_request_gen_server_OPCODE(
      op
  );
  snf_request_arg_insert(ServerRequest, arg);
  /*
      Do Whatever you want to do with Server Request
  */

• snf_request_gen_wUID

  Note

  1. UID of the custom request MUST be equal to NULLREQUEST so preferrably use snf_request_gen_server_OPCODE as it's simpler to use unles this is what you want to use
  2. If you set the UID of the custom request equal to a client Request's UID then it will make it a "Response Request with extra steps"

  // Generate your Request's OPCode 
  SNF_opcode *op = snf_opcode_get(..);
   
  // Generate your Request's Argument ( Assuming we only have one argument)
  // Remember that Content Must be a string for this version
  SNF_RQST_ARG * arg = snf_request_arg_gen("<Argument Content>");
   
   
  SNF_RQST *ServerRequest = snf_request_gen_wUID(
      NULLREQUEST
  );
  ServerRequest ->OPCODE = op;
  snf_request_arg_insert(ServerRequest, arg);
  /*
      Do Whatever you want to do with Server Request
  */

Generating Arguments

The arguments for snf 0.0.2-alpha currently require to be string representations, however this will definetly be changed in upcoming versions of the framework and protocol, so for addming you require 1 argument

1. The Content

then we'll call snf_request_arg_gen which returns a SNF_RQST_ARG *

Adding Arguments

Adding arguments to a request is easy

For Requests generated using the "Standard Method"

if you want to create your request using the Standard Method you can directly add your first argument directly when declaring your request as the 3rd argument.

Note

It is possible to use For requests generated without the "Standard Method" to register your first argument assuming you put NULL as your 3rd argument

See this for adding multiple arguments

For requests generated without the "Standard Method"

Adding your arguments requires you to generate the request first and also your arguments before adding them

and then we add them by calling snf_request_arg_insert

Example

int main()
{
    ..
 
    //Asuming our generated request is this
    SNF_RQST * Rqst;
 
    //Asuming our argument is this 
    SNF_RQST_ARG *arg;
 
    // We'll add `arg` into `Rqst`
    snf_request_arg_insert(Rqst, arg);
 
    ..
}

See this for adding multiple arguments

For multiple arguments

Technically you can use snf_request_arg_insert to add as many request as you want and not just the first argument, however if you're adding a bunch of arguments using said function is uneffective as it will keep rereading the Linked list saving the arguments over and over again,

So it's better to follow this algorithm to add them:

1. Create your First Argument in a variable

   SNF_RQST_ARG * arg1 = snf_request_arg_gen(..);

2. Add it into your request using either
   • For Requests generated using the "Standard Method"
   • For requests generated without the "Standard Method"
3. Treat the first argument as a head of a linked list and add new argument

   ..
   arg1->next = snf_request_gen(..);
   arg1 = arg1->next;
    
   ..

4. keep repeating Step 3. until you've added all of your arguments then go to Step 5.
5. You're done! now your request contains all of your arguments!

Sending Requests

If you're writing an OPCode command's function (Aka. A response function ) then you shouldn't worry about how to send your request, just return it in that function and it will be handled automatically.

However if you're sending a custom request then you must send the request through snf_request_send which requires 2 arguments

1. The Client
2. The Request to send

Important

For snf 0.0.2-alpha you must LOCK the client before Sending any request and must UNLOCK after sending your request. and NEVER DO YOUR OWN TCP COMMUNICATION ON THE SOCKET MANUALLY

Example We want to send a custom request req

...
///  Add this include
#include <pthread.h>
 
 
int main()
{
    ...
 
    // Assuming req has been created per our need
    SNF_RQST *req;
 
    // Assuming clt is our Client
    SNF_CLT * clt;
 
    pthread_mutex_lock(&(clt->mutex));
    snf_request_send(clt, req);
    pthread_mutex_unlock(&(clt->mutex));
 
    ...
}

Freeing Requests

If your request is being sent by returning said request, it will be automatically consumed and will be free'd, however for requests sent using snf_request_send must be free'd using snf_request_free which also free's arguments on it's own.

Example

int main()
{
    ...
 
    // Assuming req has been created per our need
    SNF_RQST *req;
 
    snf_request_free(req);
 
    ...
}

---

Next: SNF's Network ►