87 lines
3.4 KiB
Plaintext
87 lines
3.4 KiB
Plaintext
#PROJECT "Compound - Status" DOCUMENTATION WRITTEN BY WILLIAM PASCAL
|
|
#
|
|
#THIS PROJECT IS COMPILED UNDER "C99 ISO/IEC 9899:1999" WITH
|
|
#"gcc (GCC) 13.2.1 20230801"
|
|
#PLEASE NOTE THAT THE VERSION TO THE COMPILER MAY CHANGE DURING PROJECT
|
|
#DEVELOPMENT, IT IS UNCERTAIN, SO FAR, THAT EVERY COMPILER OLDER/NEWER THAT
|
|
#THIS VERSION COULD COMPILE PROPERLY. MS WINDOWS SUPPORT IS UNDER
|
|
#CONSIDERATION WHILE DEVELOPMENT FOR GNU/LINUX HAS HIGHER PRIORITY.
|
|
|
|
LICENSE NOTICE:
|
|
This file is part of Compound.
|
|
Compound is free software: you can redistribute it and/or modify it under
|
|
the terms of the GNU General Public License as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option) any later
|
|
version.
|
|
Compound is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
|
|
details.
|
|
You should have received a copy of the GNU General Public License along
|
|
with Compound. If not, see <https://www.gnu.org/licenses/>.
|
|
|
|
BRIEF:
|
|
"STATUS" REPRESENT THE ACTUAL PROCESS STATUS OF THE FUNCTION APPLIED TO USE
|
|
THIS STRUCTURE AS THE RETURNING TYPE.
|
|
|
|
DECLARATION:
|
|
STRUCTURE - STATUS
|
|
IT COMES WITH FOLLOWING MEMBERS:
|
|
i. value: int
|
|
|
|
"VALUE" INDICATES THE VALUE THAT FUNCTION RETURNS. MORE USUALLY, THIS
|
|
VALUE IS IGNORED WHEN "CHARACTERISTIC" IS NOT "STATUS_UNKNOWN" AS AN
|
|
ALTERNATIVE FOR LEGACY FUNCTIONS WHICH DO NOT USE "int" FOR THEIR
|
|
RETURNING.
|
|
|
|
ii. description: char*
|
|
|
|
"DESCRIPTION" TELLS THE SITUATION, USUALLY NOT NORMAL, WHERE THE FUNCTION
|
|
HAD RUN INTO CERTAIN PROBLEMS DURING THE PROCESS. IT CAN BE USEFUL WHEN
|
|
DEBUGGING AND SUCH.
|
|
|
|
*PLEASE NOTE, AN EMPTY DESCRIPTION ALONG WITH A NULL DESCRIPTION IS
|
|
REGARDED AS "MEANINGLESS ONE" WHICH DOES NOT DOING ANYTHING EFFECTIVE FOR
|
|
ANYONE. DESCRIPTIONS CAN BE VALIDATED WITH FUNCTION `status_isvalid`.
|
|
|
|
iii. characteristic: int
|
|
|
|
"CHARACTERISTIC" INDICATED THE BASIC NATURE OF CURRENT "STATUS".
|
|
|
|
*GO SEE enum StatusCharacteristics FOR AVAILABLE "CHARACTERISTICS".
|
|
|
|
iv. prev: struct _Status*
|
|
|
|
"PREV" STANDS FOR "PREVIOUS STATUS". JUST AS THE NAME TELLS, THIS MEMBER
|
|
POINTS AT THE PREVIOUS STRUCTURE OF STATUS WHERE THIS STATUS IS BASED ON.
|
|
|
|
THIS MEMBER IS USUALLY USED FOR PRINTING CALLING STACKS.
|
|
|
|
IN SOME CASES, THIS MEMBER COULD POINT AT IT SELF, MEANING IT COULD MAKE
|
|
A RECURSIVE SITUATION WHERE IT REQUIRE EXTRA EXAMINATIONS BEFORE GOING TO
|
|
THE ADDRESS IT POINTS AT. THESE PROBLEMS CAN BE AVOIDED WITH FUNCTION
|
|
`status_recursive` CALLED AHEAD.
|
|
|
|
*GO SEE status_dump FOR DETAILS ABOUT DUMPING CALLING STACKS.
|
|
*GO SEE status_recursive FOR DETERRING RECURSIVE "PREV".
|
|
|
|
SYNONYM:
|
|
Status funcname1(void *param);
|
|
Status *funcname2(void);
|
|
|
|
VARIANT SYNONYM:
|
|
int funcname1(Status stat);
|
|
void funcname2(Status *stats);
|
|
|
|
|
|
|
|
typedef struct _Status {
|
|
int value; /* Traditional returning data "int". Only used when the function
|
|
called and received legacy functions that uses "int" as the
|
|
returning type that wish to have place to hold the value.
|
|
Otherwise, the function would just return the structure Status. */
|
|
char *description;
|
|
int characteristic;
|
|
struct _Status *prev;
|
|
} Status;
|