◄ Previous: SNF's Variables
About OPCodes
opcodes is a structure meaning to define actions to be performed on both the client and server side, and it's made of 4 parts each representing an OPCode Member which is a code defining one of the 4 ranks
- Category
- SubCategory
- Command
- Detail
Currently opcodes are a set of 4 byte where each part is a byte
What to do
To make use of SNF you must define your own opcode hierachy to make use of the server
- Warning
- Your OPCodes hierachy must match with both the clients and servers, so be careful to not miss anything inbetween
To define your hierachy you must define instances of opcode members according to their ranks from to buttom, aka :
- Define the Categories
- Define the Subcategories
- Define the Commands
- Define the Details
How to:
To use the core headers of snf you can include
or if you want to include this specific header file only
This file Defines everything related to Opcodes ( Short for OP**eartion**Codes )
Precautions
Before adding anything you must initialize the opcode structure which adds the base opcodes which are mandatory for the normal running the underlying protocol.
you can do that by calling snf_opcode_init before starting anything
- Warning
- for the sake for simplicity, no error handling was included in the example
..
int main()
{
...
..
}
int snf_opcode_init()
Initializes the SNF's opcodes.
Adding OPCode Members
Add a category
Adding a category requires you 2 things
- A defining byte for the category
- A String definition of the category (OPTIONAL, can be "" or NULL);
and then we'll call snf_opcode_define_category
- Important
- The Defining byte must be different than 0 as Category with defining byte 0 is the BASE Category
- Warning
- for the sake for simplicity, no error handling was included in the example
Example We want to define a Category (0x01) for "Example things"
int main()
{
..
0x01,
"Example things"
);
...
}
int snf_opcode_define_category(SNF_opcode_mmbr_t Code, const char *Definition)
Defines an opcode Category.
Add a subcategory
- Warning
- Nerver add anything to the BASE Category (0x00)
To add a subcategory you require 3 things
- The parent category's defining byte
- A defining byte for the subcategory
- A String definition of the byte (OPTIONAL, can be "" or NULL);
and then we'll call snf_opcode_define_sub_category
- Warning
- for the sake for simplicity, no error handling was included in the example
Example We want to define a Subategory (0x00) for "Example 2"
int main()
{
...
0x01,
0x00,
"Example 2"
);
..
}
int snf_opcode_define_sub_category(SNF_opcode_mmbr_t Category, SNF_opcode_mmbr_t Code, const char *Definition)
Defines an opcode Sub-Category.
Add a command
- Warning
- Nerver add anything to the BASE Category(0x00) ( Including any Subcategory )
To add a subcategory you require 5 things
- The parent category's defining byte
- The parent subcategory's defining byte
- A defining byte for the command
- A function that would be called if the client raises this opcode.
- A String definition of the byte (OPTIONAL, can be "" or NULL);
and then we'll call snf_opcode_define_command
- Warning
- for the sake for simplicity, no error handling was included in the example
Example We want to define a Command (0x00) for "Example Command"
First we must define our function that would be called when a connected client raises this opcode
- Note
- The Function MUST take a SNF_RQST * as an argument, which is the client's original request, and the return of this function will be sent to the client if it is not NULL.
More about request is documented at SNF's Requests.
{
return <Your Response Reqst or NULL>;
}
The Structure for saving Requests.
Definition request.h:27
then
int main()
{
...
0x01,
0x00,
0x00,
"Example Command",
respondtoclient
);
...
}
int snf_opcode_define_command(SNF_opcode_mmbr_t Category, SNF_opcode_mmbr_t SubCategory, SNF_opcode_mmbr_t Code, const char *Definition, SNF_RQST *(func)(SNF_RQST *))
Defines an opcode Command.
Add a command's detail
- Warning
- Nerver add anything to the BASE Category(0x00) ( Including any Subcategory or Command )
- Note
- Details are not mandatory, and are extentions for the Commands.
by default every command will have one detail whose defining byte equals to 0x00 (Click to see more) so any detail you add to any command MUST start with 0x01
To add a subcategory you require 5 things
- The parent category's defining byte
- The parent subcategory's defining byte
- The parent command's defining byte
- A defining byte for the command's detail
- A String definition of the byte (OPTIONAL, can be "" or NULL);
and then we'll call snf_opcode_define_detail
- Warning
- for the sake for simplicity, no error handling was included in the example
Example We want to define a Detail(0x01) for "Example Detail"
int main()
{
...
0x01,
0x00,
0x00,
0x01,
"Example Detail"
);
...
}
int snf_opcode_define_detail(SNF_opcode_mmbr_t Category, SNF_opcode_mmbr_t SubCategory, SNF_opcode_mmbr_t Command, SNF_opcode_mmbr_t Code, const char *Definition)
Defines an opcode Detail.
Generate OPCodes
After defining your opcode structure, you're gonna need to generate opcodes to use in your requests.
Generate a Detailed OPCode
a "Detailed OPCode" is an OPCode that has a detail member whose defining byte differs from SNF_OPCODE_BASE_DET_UNDETAILED (0x00)
which requires you 4 Arguments
- The category's defining byte
- The subcategory's defining byte
- The command's defining byte
- The command detail's defining byte and then we'll call snf_opcode_get
Example
int main()
{
...
0x01,
0x00,
0x00,
0x01
);
...
}
SNF_opcode * snf_opcode_get(SNF_opcode_mmbr_t Category, SNF_opcode_mmbr_t SubCategory, SNF_opcode_mmbr_t Command, SNF_opcode_mmbr_t Detail)
Fetches a fully structured OPcode.
Structure for the opcode.
Definition opcode.h:28
Generate an Undetailed OPCode
an "Detailed OPCode" is an opcode that has a detail member whose defining byte does not differ from SNF_OPCODE_BASE_DET_UNDETAILED (0x00), which requires the same as Generating a detailed command execpt it doesnt require the defining byte to a detail
and then we'll call snf_opcode_getu
Example
int main()
{
...
0x01,
0x00,
0x00
);
...
}
SNF_opcode * snf_opcode_getu(SNF_opcode_mmbr_t Category, SNF_opcode_mmbr_t SubCategory, SNF_opcode_mmbr_t Command)
Fetches a fully structured OPcode using the default Detail.
Generate a Detailed Base OPCode
a "Detailed base OPCode" is a Base OPCode that has a detail member whose defining byte differs from SNF_OPCODE_BASE_DET_UNDETAILED (0x00)
which requires you only 2 Arguments
- The command's defining byte
- The command detail's defining byte
and then we'll call snf_opcode_get_base
Example we want to get an opcode with The base command INVALID with the ERROR_PROTOCOL Detail
int main()
{
...
);
...
}
#define SNF_OPCODE_BASE_CMD_INVALID
When client's request was invalid either, wrong version or incomplete request.
Definition opcode.h:260
#define SNF_OPCODE_BASE_DET_INVALID_ERROR_PROTOCOL
Protocol used is invalid.
Definition opcode.h:264
SNF_opcode * snf_opcode_get_base(SNF_opcode_mmbr_t Command, SNF_opcode_mmbr_t Detail)
Fetches a fully structured OPcode with a base "Command".
- Note
- For the INVALID
Generate a Detailed Base OPCode
an "Unetailed base OPCode" is a Base OPCode that has a detail member whose defining byte does not differ from SNF_OPCODE_BASE_DET_UNDETAILED (0x00)
which requires you only 1 Arguments
- The command's defining byte
and then we'll call snf_opcode_getu_base
Example we want to get an opcode with The base command CONFIRM
int main()
{
...
);
...
}
SNF_opcode * snf_opcode_getu_base(SNF_opcode_mmbr_t Command)
Fetches a fully structured OPcode witha base "Command" using the default Detail.
#define SNF_OPCODE_BASE_CMD_CONFIRM
When client's reuqest was confirmed.
Definition opcode.h:252