The Internet Protocol for Netgraph Client-Server Communication
At the server side, the messages are processed in function reseni (dotser.c).
Most of the names are defined in file mutual.h, some are defined in other header/implementation files.
Legend:
Names of one-character constants/variables are enclosed in [] (e.g. [EOM])
Names of strings are enclosed in {} (e.g. {login_name})
Constants are written in capital letters (e.g. [EOL])
Names of lists of predefined constants are written with first letter capitalized (e.g. {Property_Label})
Names of arbitrary characters/strings are written in low letters (e.g. {login_name})
------------------------------------------
GETVERSION (a request for a version of the client/server)
C: [GETVERSION][Type_Of_The_Version][EOM]
where: [Type_Of_The_Version] is one of:
[SERVER_VERSION] (the version of the server)
[CLIENT_REQUIRED_VERSION] (the required version of the client to work properly with the server)
[CLIENT_RECOMMENDED_VERSION] (the recommended version of the client to take advantage of all features of the server)
S: [OK]{version}[EOM]
------------------------------------------
GET_INIT_INFO (a request for a bundle of initial information)
C: [GET_INIT_INFO][EOM]
S: [ERROR][EOM] (if an error occurs)
[OK]{server_version}[EOL]
{client_required_version}[EOL]
{initial_path_of_the_treebank}[EOL]
{client_recommended_version}[EOL]
{treebank_identifier}[EOL]
({coreference_pattern}[EOL])+
[EOL]
[EOM]
------------------------------------------
PWD (a request for the actual directory in the treebank)
C: [PWD][EOM]
S: [OK]{actual_directory}[EOM]
------------------------------------------
CD (a request to change the actual directory in the treebank)
C: [CD]{relative_path_to_the_new_directory}[EOM]
S: [OK]{new_actual_directory}[EOM] (if the change was successful)
[ERROR][EOM] (if an error occurs, like the new directory is out of the directory structure accessible to the user)
------------------------------------------
GETDIRS (a request for the list of subdirectories in the actual directory in the treebank)
C: [GETDIRS][Type_Of_The_Part][EOM]
where: [Type_Of_The_Part] is one of:
[PART_FIRST] (the client expects the first (possibly the only one) part of the list of directories)
[PART_MIDDLE] (the client expects the next (possibly last) part of the list of directories)
S: [ERROR][EOM] (if an error occurs)
[OK][Type_Of_The_Part]({directory}[TAB])*{directory}+[EOM]
where: [TAB] is a tabulator ('\t')
[Type_Of_The_Part] is one of:
[PART_ONLY] (the whole list of directories is being sent in this one message)
[PART_FIRST] (the list of directories is too long for one message; this is the first part)
[PART_MIDDLE] (the list of directories is too long for one message; this is neither the first nor the last part)
[PART_LAST] (the list of directories is too long for one message; this is the last part)
------------------------------------------
GETFILES (a request for the list of files in the actual directory in the treebank)
C: [GETFILES][Type_Of_The_Part][EOM]
where: [Type_Of_The_Part] is one of:
[PART_FIRST] (the client expects the first (possibly the only one) part of the list of files)
[PART_MIDDLE] (the client expects the next (possibly last) part of the list of files)
S: [ERROR][EOM] (if an error occurs)
[OK][Type_Of_The_Part]({file}[TAB])*{file}+[EOM]
where: [TAB] is a tabulator ('\t')
[Type_Of_The_Part] is one of:
[PART_ONLY] (the whole list of files is being sent in this one message)
[PART_FIRST] (the list of files is too long for one message; this is the first part)
[PART_MIDDLE] (the list of files is too long for one message; this is neither the first nor the last part)
[PART_LAST] (the list of files is too long for one message; this is the last part)
------------------------------------------
GET_TAIL (sending of the content of the actual file found after the trees)
C: [GET_TAIL][EOM]
S: [OK]{tail_of_the_file}[EOM]
where: {tail_of_the_file} is written in function getTail (dotser.c)
------------------------------------------
SETFILES (setting a list of files for searching)
C: [SETFILES][Type_Of_The_Part]({file/dir_name}[TAB])*{file/dir_name}*[EOM]
where: [TAB] is a tabulator ('\t')
[Type_Of_The_Part] is one of:
[PART_ONLY] (the whole list of files is being sent in this one message)
[PART_FIRST] (the list of files is too long for one message; this is the first part)
[PART_MIDDLE] (the list of files is too long for one message; this is neither the first nor the last part)
[PART_LAST] (the list of files is too long for one message; this is the last part)
S: [OK][EOM] (for [Type_Of_The_Part] one of [PART_FIRST] and [PART_MIDDLE])
[OK]{global_head}[EOM] (for [Type_Of_The_Part] one of [PART_ONLY] and [PART_LAST])
where: {global_head} is a union of attributes, their types and possible values, generated in function vypis_hlavicku (dotser.c)
------------------------------------------
QUERY (setting a query - a request for searching in the treebank)
C: [QUERY][ALL_TREES][EOM] (a request for all trees in the selected files)
[QUERY][ABOVE_FILES][log_exp_position][Match_Lemma_Variants][Match_Lemma_Comments][Invert_Match][First_Only]{Logical_Expr}[EOL]{QUERY_1}[EOL]...{QUERY_N}[EOM]
(a request for trees matching the query, from the selected files, use logical expression to combine trees in the query)
[QUERY][ABOVE_RESULT][log_exp_position][Match_Lemma_Variants][Match_Lemma_Comments][Invert_Match][First_Only]{Logical_Expr}[EOL]{QUERY_1}[EOL]...{QUERY_N}[EOM]
(a request for trees matching the query, from the result of the previous query, use logical expression to combine trees in the query)
[QUERY][ABOVE_FILES][query_position][Match_Lemma_Variants][Match_Lemma_Comments][Invert_Match][First_Only]{QUERY_1(starting with '['}[EOL]...{QUERY_N}[EOM]
(a request for trees matching the query, from the selected files, use AND to combine trees in the query)
[QUERY][ABOVE_RESULT][query_position][Match_Lemma_Variants][Match_Lemma_Comments][Invert_Match][First_Only]{QUERY_1(starting with '['}[EOL]...{QUERY_N}[EOM]
(a request for trees matching the query, from the result of the previous query, use AND to combine trees in the query)
S: [ERROR][EOM] (if an unspecified error occurs)
[ERROR][Error_Type]{error_description}[EOM] (if a specified error occurs (like an error in regular expression))
[REPEAT][EOM] (in case a query above the previous result is being set and the previous searching has not yet finished)
[OK][Specifier][EOM] (if the query has been successfully set; [Specifier] is ignored by the client)
------------------------------------------
STOP (an explicit request to stop the searching)
C: [STOP][EOM]
S: the response of the server is identical to GET_STATISTICS (get statistics)
------------------------------------------
GET_STATISTICS (a request for actual statistics about searching)
C: [GET_STATISTICS][EOM]
S: [OK]{number_of_actual_occurrence}[EOL]
{number_of_actual_tree}[EOL]
{number_of_found_occurrences}[EOL]
{number_of_found_trees}[EOL]
{number_of_searched_trees}[EOL]
[EOM]
------------------------------------------
GETN (a request for the next result)
C: [GETN][Subtype][EOM] (next occurrence/tree/context tree)
where: [Subtype] is one of:
[PREV_FIRST_OCCURRENCE] (a request for the first result)
[NEXT_OR_PREV_CONTEXT] (a request for the subsequent context tree)
[NEXT_OR_PREV_TREE] (a request for the next result tree)
[NEXT_OR_PREV_OCCURRENCE] (a request for the next occurrence)
S: [END_OF_SEARCHING][END_OF_SEARCHING_MAX_NUMBER_REACHED]{statistics}[EOM] (no next tree - maximum allowed number reached)
[END_OF_SEARCHING][END_OF_SEARCHING_NO_NEXT_TREE]{statistics}[EOM] (no next tree - there is no next result tree in the selected files)
[FILE_BOUNDARY_REACHED]{statistics}[EOM] (no next context tree in the file)
[ERROR]{statistics}[EOM] (no next found tree; still searching)
[OK][?]\n{file_name}\n{matching_nodes}\n{statistics[EOL]}{fs_head}\n{fs_tree}[EOM] (next tree sent)
where: {statistics} are the same statistics like in [GET_STATISTICS]
[?] - remains to be documented
------------------------------------------
GETP (a request for the previous result)
C: [GETP][Subtype][EOM] (previous occurrence/tree/context tree)
where: [Subtype] is one of:
[NEXT_OR_PREV_CONTEXT] (a request for the previous context tree)
[NEXT_OR_PREV_TREE] (a request for the previous result tree)
[NEXT_OR_PREV_OCCURRENCE] (a request for the previous occurrence)
S: [ERROR]{statistics}[EOM] (an error occurred)
[OK][?]\n{file_name}\n{matching_nodes}\n{statistics[EOL]}{fs_head}\n{fs_tree}[EOM] (next tree sent)
where: {statistics} are the same statistics like in [GET_STATISTICS]
[?] - remains to be documented
------------------------------------------
REMOVE_OCCURRENCE (removing of the actual tree from the result)
C: [REMOVE_OCCURRENCE][EOM]
S: the response of the server is identical to GETN (get next tree)
------------------------------------------
LOGIN (authentication of the user or password change)
C: [LOGIN][LOGIN_AUTHENTIZE]{login_name}[EOL]{md5_encoded_password}[EOL][EOM] (a request to login with a name and password (encoded with MD5))
S: [OK][EOM]({Property_Label}[CLIENT_COMMUNICATION_LABEL_DELIMITER]{property_value}[CLIENT_COMMUNICATION_FIELDS_DELIMITER])+[EOM]
where: {Property_Label} - labels of properties are defined in passwd.c
[ERROR][Error_Type][EOM] (if an error occurs)
where [Error_Type] is (defined in passwd.h):
[ERROR_USER_DOES_NOT_EXIST] (if the login_name does not exist)
[ERROR_ACCOUNT_DISABLED] (if the account has been disabled)
[ERROR_WRONG_PASSWORD] (if the password is wrong)
[ERROR_CANNOT_READ_FILE] (if the reading from the file with passwords failed)
[ERROR_CANNOT_ALLOCATE_MEMORY] (if an error while allocating memory occurred)
[ERROR_ANOTHER_ERROR] (if some other error occurred)
C: [LOGIN][LOGIN_CHANGE_PASSWORD]{login_name}[EOL]{md5_encoded_old_password}[EOL]{md5_encoded_new_password}[EOL][EOM]
S: [OK][EOM] (if successfully changed)
[ERROR][Error_Type][EOM] (if an error occurs)
where [Error_Type] is (defined in passwd.h):
[ERROR_USER_DOES_NOT_EXIST] (if the login_name does not exist)
[ERROR_ACCOUNT_DISABLED] (if the account has been disabled)
[ERROR_WRONG_OLD_PASSWORD] (if the old_password is wrong)
[ERROR_NO_CHANGE_PASSWORD_PERMISSION] (if the user has not permission to change his password)
[ERROR_CANNOT_READ_FILE] (if the reading from the file with passwords failed)
[ERROR_CANNOT_WRITE_FILE] (if the writing to the file with passwords failed)
[ERROR_CANNOT_ALLOCATE_MEMORY] (if an error while allocating memory occurred)
[ERROR_ANOTHER_ERROR] (if some other error occurred)
------------------------------------------
CLIENT_EXITED (the client ended the connection)
C: [CLIENT_EXITED][EOM]
S: no response
------------------------------------------
------------------------------------------
Notes (do not belong here):
metaatributy a vyznamove atributy v dotazu:
hide: lze definovat jen v prvni sade atributu (tedy ne v alternativnim uzlu), lze pouzit
ve variantach hodnot (tedy mohu rict hide=true|false)
mozne hodnoty: prazdna hodnota, "0" a "false" znamenaji neskryty uzel, ostatni hodnoty skryty uzel
atribut musi byt definovany pouze s relaci '='
_name: muze byt definovano jen v prvni sade atributu, jen s jednou hodnotou
_transitive: muze byt definovano ve vice sadach, pokazde jen s jednou hodnotou
_optional: muze byt definovan v kterekoliv sade, ale u vrcholu jen jednou (nema smysl ve vice sadach, vrchol je bud cely optional nebo ne)
rovnez muze byt definovan jen s jednou hodnotou (protoze _optional=1|2|3 je to same jako _optional=3) a jen s rovnitkem;
nemuze byt definovan u korene dotazu