12.2 Text Protocol Server - reading input

The code for parsing input can be find in src/server/read.c. There are generally two types of functions - ones read the whole structures and the others read basic lexical elements (numbers, strings etc.) All the functions directly parse in the language used by SurpriseServer which is described in section Description of Text Protocol API.

Functions reading and filling data structure

All these functions have either three or four parameters. The first one is an opened filehandle form which the input is read. The second one is a pointer to the (already allocated) structure to read. In case of four parameter function the third parameter is a pointer to the already read first element of the language construction of the data structure to read. The last parameter is a pseudoparameter of Suprise error system. The value returned by functions is zero if no error occured and negative otherwise; value -1 represents a parse (not I/O or any other) error.

All these functions use special input functions for reading characters from input stream: read_next(int, char **, ERR_PARAM) reads in the next lexical element (a tag quoted by < and >, a string quoted by " etc.). This function calls function read_next_char(int, char *, ERR_PARAM which reads in the next character from input stream. The only function calling read_next_char is read_next.

int read_final(int, struct final *, ERR_PARAM)

This function reads in description of and fills in struct final. This function calls read_disk, read_parameter and read_next.

int read_disk(int, struct disk_info *, char *, ERR_PARAM)

This function reads in description of and fills in struct disk_info. This function calls read_partition, read_parameter, read_str, read_short, read_num and read_next.

int read_partition(int, struct user_partition *, char *, ERR_PARAM)

This function reads in description of and fills in struct user_parameter. This function calls read_directory, read_parameter, read_num, read_str, read_guint8, read_guint32 and read_next.

int read_directory(int, struct user_directory *, char *, ERR_PARAM)

This function reads in description of and fills in struct user_directory. This function calls read_str and read_num.

int read_parameter(int, struct user_parameter *, char *, ERR_PARAM)

This function reads in description of and fills in struct user_parameter. The function reads in user parameters of all the five types. This function calls read_flag, read_str, read_num, read_long and read_next.

Functions reading basic lexical elements

All these functions have three parameters (only read_flag has two parameters and the element read by it is returned as the function result and read_str has an additional pseudoparameter of Surprise error system). The first one is a double pointed char. It represents a pointer to the buffer; if reading the element is successful then the pointer is moved after the read characters, otherwise the pointer is preserved. The second parameter is a pointer to char and it can be NULL. This string (if not NULL) precedes the characters to read in the buffer. The third parameter is the buffer for storing the read value.

int read_flag(char **,const char *)

This function reads in boolean flag represented by (non)-presence of string pointed by the second parameter.

int read_str(char **,const char *,char **,ERR_PARAM)

This function reads in string quoted by quotation marks (").

int read_num(char **,const char *,int *)

This function reads in a non-negative integer number; if t is not NULL then between the token and the number is an equal sign.

int read_guint8(char **,const char *,guint8 *)

This function reads in a non-negative 8-bit integer number; if t is not NULL then between the token and the number is an equal sign.

int read_guint32(char **,const char *,guint32 *)

This function reads in a non-negative 32-bit integer number; if t is not NULL then between the token and the number is an equal sign.

int read_short(char **,const char *,short *)

This function reads in a non-negative short integer number; if t is not NULL then between the token and the number is an equal sign.

int read_long(char **,const char *,long *)

This function reads in a non-negative long integer number; if t is not NULL then between the token and the number is an equal sign.