CLI interface Calom serveru

Úvod

Komunikace s Calom serverem je možná prostřednictvím CLI rozhraní. Jedná se o textovou síťovou komunikaci postavenou nad protokolem TCP.

Klient posílá požadavky (příkazy nebo dotazy) a server posílá odpovědi rozdělené do řádků, kde každý řádek začíná návratovým kódem.
Jednotlivé řádky jsou oddělené znamek LF (kód 10) a mohou (v závislosti na typu příkazu obsahovat libovolné 8-mi bitové znaky s výjimkou NULL(0), LF(10), CR(13). U některých příkazů je nutné dávat parametry do uvozovek (").

Stejné příkazy, které lze použít v CLI rozhraní, jsou dostupné i ze souboru config (a naopak).

Zahájení komunikace

Klient se připojí na Calom server TCP port (implicitně 7777) a server pošle identifikační řádku ve formátu:

CALOM <verze serveru> ready. Please log in.

Klient odpoví řádkem obsahujícím uživatelské jméno:

guest

Server odpoví řádkem s kódem SO_PASSWD, je-li možné poslat heslo, nebo chybovým kódem, pokud autentizace selhala.
Klient pošle heslo (v plain-textu):

guest-passwd

Server odpoví řádkem s kódem SO_LOGGED_IN, je-li přihlášení úspěšné, nebo chybovým kódem, pokud autentizace selhala.
Pokud je přihlášení úspěšné, je možné pokračovat zadáváním příkazů.

Popis komunikace

Požadavky se posílají na řádce, která má tvar:

<příkaz> [<parametr> ...]

Příkaz může být tvořen jedním nebo více slovy. Víceslovné příkazy jsou hierarchické, počáteční slova může sdílet několik příkazů, např. "DIR LIST" nebo "DIR ADD".

Formát parametrů závisí na příkazu. Některé příkazy nemají parametry, některé mají nepovinné nebo povinné parametry. Jednotlivé parametry se oddělují mezerou.
Jsou dva možné způsoby zadávání parametrů.

Univerzální způsob je psát vždy jméno parametru a potom hodnotu parametru (oddělené mezerou).
Parametry je možné psát v libovolném pořadí.
Až do prvního S nebo K parametru (viz. níže) je možné psát přímo hodnoty parametrů za sebe v pořadí, v jakém jsou uvedeny v popisu příkazu.
Pokud je možné, aby hodnota parametru byla stejná jako jméno jednoho z parametrů, je potřeba psát hodnoty parametru do uvozovek, aby nebyly interpretovány jako jména parametrů.
Kombinace obou způsobů. Je možné začít psát přímo hodnoty parametrů v pořadí, v jakém jsou uvedeny v popisu příkazu (doporučeno dávat do uvozovek) a od v určitém místě začít psát jména parametrů jako v prvním případě. Po prvním jménu parametru ale již není možné se vrátit k psaní pouze hodnot.

Příklady:

dir add "Prodej.Marketing" "123456" "Kamil Prochazka" "0"
dir add "Prodej.Marketing" "123456" "Kamil Prochazka" "0" "3234" "Kamil od vedle"
dir add "Prodej.Marketing" "123456" "Kamil Prochazka" "0" "3234" "Kamil od vedle" PREFIX
dir add Prodej.Marketing 123456 "Kamil Prochazka" 0 3234 "Kamil od vedle" PREFIX
dir add ORG "Prodej.Marketing" NUM "123456" NAME "Kamil Prochazka" CAT "0"
dir add ORG "Prodej.Marketing" NUM "123456" NAME "Kamil Prochazka" CAT "0" PREFIX
dir add NUM "123456" NAME "Kamil Prochazka" ORG "Prodej.Marketing" PREFIX CAT "0"

Pokud hodnoty parametrů obsahují mezeru nebo jiný interpretovaný znak, je třeba je dávat do uvozovek.

Odpovědi mají tvar:

<kód><flag konce><vlastní text>

Kód je 4-číselný decimální kód řádku odpovědi, viz. následující tabulky. Kód 0000 (SO_OK) znamená úspěšně splněný příkaz, kódy začínající číslicí 2 znamenají chybu, kódy začínající číslicí 3 označují určitý typ dat odpovědi.

Pokud je daný řádek posledním řádkem odpovědi, je <flag konce> mezera, má-li pokračování, je <flag konce> pomlčka (-).

Vlastní text odpovědi je buď pouze informativní (např. v případě kódu SO_OK, tj. 0000) nebo obsahuje data odpovědi. Formát dat závisí na kódu odpovědi.

Komentáře

Řádka s komentářem začíná znakem středník (";"), který musí být na první pozici na řádce.

Příkazy HELP a parametr ?

Příkaz HELP vypíše základní informaci o CLI příkazech.

Pro zjištění formátu určitého příkazu je možné použít napsat příkaz nebo jen počáteční slovo/slova příkazu a jako parametr uvést ?.
Odpověď je popis příkazu a jeho parametrů. U parametru jsou lomítkem odděleny vlastnosti parametru:

A - Povinný parametr
N - Číselný parametr (implicitně string)
K - Klíčové slovo. Pro specifikaci je nutné napsat jméno parametru, mezeru a hodnotu
S - Switch. Podobně jako K, ale nemá hodnotu. Příklad: ON nebo OFF.

Ukončení komunikace

Komunikaci je možné ukončit zasláním příkazu EXIT nebo ukončením TCP spojení.

Návratové kódy

Tabulka kódů jednotlivých řádek odpovědi pro úspěšné operace:

Název Číselný kód Chybové hlášení Poznámka

SO_OK 0 Operace úspěšně provedena

SO_HELLO 3000 Uvítací hlášení (viz výše)

SO_PASSWD 3001 Password: Výzva k zadání hesla

SO_LOGGED_IN 3002 Welcome, <jméno uživatele>. Při úspěšném přihlášení

SO_HELP 3003 Řádka obsahuje nápovědu

SO_GOODBYE 3004 Good bye... Při odhlášení

SO_DEBUGGING 3005 Řádka obsahuje ladicí informace

SO_USER_INFO 3006 Řádka obsahuje informace o uživateli

SO_USER 3007 Řádka obsahuje položku seznamu uživatelů

SO_DUMPED 3008 Database dumped

SO_AUTH_LIST 3009 Řádka obsahuje položku seznamu povolených domén (dirdb)

SO_ORG_ENTRY 3010 Řádka obsahuje položku seznamu organizačních domén (dirdb)

SO_DIR_ENTRY 3011 Řádka obsahuje položku výpisu organizační domény (dirdb)

SO_DIR_INFO 3012 Řádka obsahuje detailní informace o dirdb záznamu (dirdb)

SO_GATH_ENTRY 3013 Řádka obsahuje položku seznamu gathererů

SO_HEADING 3014 Řádka obsahuje záhlaví výpisu (např. seznamu gathererú)

SO_FILTER 3015 Řádka obsahuje položku seznamu filtrů - popis filtru

SO_SHUTDOWN 3016 Server shut down

SO_REPORT_NAME 3017 Řádka obsahuje položku seznamu reportů

SO_REPORT_PULSE_COST 3018 Řádka obsahuje cenu pulzu v reportu

SO_REPORT_LINE 3019 Řádka obsahuje řádku definice reportu

SO_CALL_DATA 3020 Řádka obsahuje záznam o hovoru (používá se pro synchronizaci dvou Calom serverů)

SO_REPORT_RESULT 3021 Řádka obsahuje řádku výstupu reportu

SO_CALL_DATA_DAY 3022 Řádka obsahuje záznam o začátku nového dne (používá se pro oddělení řádků SO_CALL_DATA)

SO_PROCESSING_REPORT 3023 Report in progress...

SO_LOCAL_TIME 3024 Řádka obsahuje informaci o času serveru

SO_VERSION 3025 Řádka obsahuje informaci o verzi serveru

SO_UPTIME 3026 Řádka obsahuje informaci o času uptime serveru

SO_IMPOSVER 3027 Řádka obsahuje informaci o verzi IMPOS systému

SO_LOGGING 3028 <typ ("Console" nebo "Logfile")>: DEBUG=<číslo> INFO=<číslo> LOG=<číslo> AUTH=<číslo>, WARN=<číslo>, AUTHFAIL=<číslo>, ERR=<číslo>, SYS=<číslo>, FATAL=<číslo>, PANIC=<číslo> Řádka obsahuje informaci o nastavených úrovních jednotlivých hlášení do log souboru

SO_WHO 3029 <uživ. jméno>\t<jméno tasku> Řádka obsahuje informaci o přihlášeném uživateli

SO_CILDIR_STATUS 3030 CIL codes <"contain" nebo "don't contain"> DIR numbers Řádka obsahuje informaci zda jsou v CIL kódech hledána telefonní čísla

SO_TARIF 3031 Řádka obsahuje informaci o tarifu

SO_TARIF_DUMP 3032 Řádka obsahuje řádku definice tarifu

SO_HELPER 3033 Řádka obsahuje informaci o pomocné aplikaci (tzv. helperu)

SO_HELPER_LIST 3034 Řádka obsahuje položku seznamu helperů

SO_CONFIG_DUMP 3035 Řádka obsahuje řádku konfiguračního souboru

SO_TARIF_FLAG_DUMP 3036 Řádka obsahuje informaci o nastavení tarifu

SO_LICENSE_DUMP 3037 <id>: <popis> Řádka obsahuje informaci o licenci

Při chybě jsou odpovědi většinou jednořádkové a první řádka obsahuje chybový kód.
Tabulka chybových kódů odpovědi:

Název Číselný kód Chybové hlášení

SE_CURRENT_NOT_SET 2000 Current position not set

SE_BAD_PASSWORD 2001 Invalid password

SE_USERNAME_TOO_LONG 2002 User name too long

SE_PASSWORD_TOO_LONG 2003 Password too long

SE_USER_ALREADY_EXISTS 2004 User already exists

SE_INVALID_NAME 2005 Invalid name

SE_BLOCK_ALREADY_DEFINED 2006 Authentication block already defined

SE_NOBODY_LOGGED_IN 2007 Nobody logged in

SE_PERMISSION_DENIED 2008 Permission denied

SE_DISK_ERROR 2009 Disk error

SE_LINE_TOO_LONG 2010 Line too long

SE_END_OF_FILE 2011 End of file

SE_UNKNOWN_ERROR 2012 Unknown error

SE_NO_SUCH_USER 2013 No such user

SE_UNKNOWN_COMMAND 2014 Unknown command

SE_REQUIRED_ARGUMENT_MISSING 2015 Required argument missing

SE_TOO_MANY_ARGUMENTS 2016 Too many arguments

SE_ARGUMENT_ENTERED_TWICE 2017 Argument entered twice

SE_BAD_NUMBER 2018 Bad number

SE_BAD_QUOTING 2019 Illegal quoting

SE_KEYWORD_NEEDS_ARGUMENT 2020 Keyword needs an argument

SE_BAD_ARGS 2021 Illegal argument

SE_NO_SUCH_TASK 2022 No such task

SE_TMP_FILE_FAIL 2023 Temporary file fault

SE_NO_SUCH_BLOCK 2024 No such authentication block

SE_NO_SUCH_ORG 2025 No such organization unit

SE_NO_SUCH_DIR 2026 No such directory entry

SE_DIR_ALREADY_EXISTS 2027 Directory entry already exists

SE_ORG_ALREADY_EXISTS 2028 Organization unit already exists

SE_NOT_EMPTY 2029 Not empty

SE_DIR_NO_ALREADY_EXISTS 2030 Directory number already exists

SE_ROOT_DEL 2031 Tree root cannot be deleted

SE_CILC_ALREADY_EXISTS 2032 CIL code already exists

SE_NO_SUCH_CILC 2033 No such CIL code

SE_INVALID_ORG 2034 Invalid organization unit name

SE_INVALID_CAT 2035 Invalid category

SE_NO_SUCH_GATHERER 2036 No such gatherer

SE_GATH_ALREADY_RUNNING 2037 Gatherer already running

SE_PARAM_STR_TOO_LONG 2038 Parameter string too long

SE_KILL_IMPOSSIBLE 2039 Gatherer cannot be killed

SE_UNKNOWN_GATH_TYPE 2040 Invalid gatherer type

SE_ILLEGAL_TIME 2041 Invalid time

SE_POSITION_NOT_FOUND 2042 Position not found

SE_EMPTY_FILTER 2043 Empty filter

SE_FILTER_SYNTAX 2044 Line-Filter syntax error

SE_KEYWORD_EXPECTED 2045 Line-Filter keyword expected

SE_CANNOT_BE_SET 2046 Cannot be set

SE_OUT_OF_RANGE 2047 Out of range

SE_BAD_DATE 2048 Illegal date

SE_BAD_PATTERN 2049 Illegal pattern

SE_NO_SUCH_REPORT 2050 No such report

SE_RTASK_ERR 2051 Cannot create report subtask

SE_RTASK_DIED 2052 Report subtask died

SE_UNKNOWN_SYMBOL 2053 Unknown symbol on line %d

SE_INVALID_CHAR 2054 Invalid character on line %d

SE_REPORT_FAILED 2055 Report failed

SE_REPORT_PARSE 2056 Report parse error on line %d

SE_PARSER_STACK 2057 Report parser stack overflow

SE_INTERNAL_ERROR 2058 Internal error (see log)

SE_INVALID_TIME_RANGE 2059 Invalid time range on line %d

SE_EMPTY_REPORT_OP 2060 Empty report operation on line %d

SE_KEY_REQUIRED 2061 Merging key required on line %d

SE_KEY_NOT_ALLOWED 2062 Merging key not allowed on line %d

SE_INVALID_SLICE 2063 Invalid slicer on line %d

SE_INVALID_SLICE2 2064 Invalid slicer

SE_INVALID_FORMSTR 2065 Invalid format string

SE_MERGE_ONLY_NUM 2066 MIN/MAX merging allowed only for numeric items

SE_INVALID_CILC 2067 Invalid CIL code

SE_INVALID_NUM 2068 Invalid directory number

SE_DIR_ITEM_TOO_LONG 2069 Directory item too long

SE_INVALID_MOVE 2070 Cannot move to own subtree

SE_GROUP_INSIDE_GROUP 2071 Invalid grouping

SE_BREAK 2072 Interrupt

SE_FILE_NOT_FOUND 2073 File not found

SE_SCRIPT_NOT_FOUND 2074 Script not found

SE_PARSE_ERROR 2075 Parse error

SE_INVALID_ARGUMENT 2076 Invalid argument

SE_SCRIPT_ALREADY_PARSED 2077 The script has already been parsed

SE_SCRIPT_ALREADY_EXISTS 2078 Script already exists

SE_SCRIPT_ERROR 2079 Error executing script - consult log files

SE_SCRIPT_IS_IN_USE 2080 Cannot remove script, it is in use

SE_SOURCE_NOT_AVAILABLE 2081 Script source is not available

SE_NOT_IMPLEMENTED 2082 Function not implemented

SE_SCRIPT_NOT_GLOBAL 2083 Script not global

SE_SCRIPT_PARSE_ERROR 2084 Error parsing inline script

SE_INVALID_PATH 2085 Invalid path

SE_SCRIPT_SAVE_ERROR 2086 Error saving script

SE_HELPER_NOT_FOUND 2087 Helper not found

SE_HELPER_ALREADY_EXISTS 2088 Helper already exists

SE_ERROR_RUNNING_HELPER 2089 Error running helper

SE_HELPER_ERROR 2090 Operation with helper failed

SE_CONFIG_LOCK_ERROR 2091 Error locking/unlocking config file

SE_CONFIG_LOCKED 2092 Config file locked by somebody else

SE_CANNOT_WRITE_FILE 2093 Cannot write file

SE_FILE_OP_ERROR 2094 Error manipulating with file

SE_SCRIPT_SYMBOL_NOT_FOUND 2095 Script symbol not found

SE_SCRIPT_SYMBOL_INCOMPATIBLE 2096 Script symbols are not compatible

SE_CONFIG_NOT_LOCKED 2097 Config file has to be locked first

SE_CONFIG_TRANSACTION_ERROR 2098 Error during config file transaction

SE_NO_SUCH_LINE 2099 No such line

SE_INVALID_STATE 2100 Invalid state

SE_NOT_LICENSED 2101 Invalid/missing license

SE_LICENSE_VIOLATION 2102 License violation

SE_RECORD_NOT_FOUND 2103 Record not found

Poznámky:

Pro zadávání příkazů je možné použít libovolné znaky s výjimkou NULL(0), LF(10), CR(13)
Řádky je nutné oddělovat znakem LF(10)
Maximální délka příkazu je 1999 znaků, max. délka parametrů je závislá na příkazu
Při komunikaci je nastaven timeout (implicitně 5 minut), po kterém server ukončí spojení
Pro zabezpečení komunikace je nutné použít SSL tunelování. Viz dokument o bezpečnosti
Příkazy jsou podrobně popsány v dokumentu Intro.

Popisovaná verze Calom serveru: 2.3.1

Poslední úprava: 29.8.2006

Název	Číselný kód	Chybové hlášení	Poznámka
SO_OK	0		Operace úspěšně provedena
SO_HELLO	3000		Uvítací hlášení (viz výše)
SO_PASSWD	3001	Password:	Výzva k zadání hesla
SO_LOGGED_IN	3002	Welcome, <jméno uživatele>.	Při úspěšném přihlášení
SO_HELP	3003		Řádka obsahuje nápovědu
SO_GOODBYE	3004	Good bye...	Při odhlášení
SO_DEBUGGING	3005		Řádka obsahuje ladicí informace
SO_USER_INFO	3006		Řádka obsahuje informace o uživateli
SO_USER	3007		Řádka obsahuje položku seznamu uživatelů
SO_DUMPED	3008	Database dumped
SO_AUTH_LIST	3009		Řádka obsahuje položku seznamu povolených domén (dirdb)
SO_ORG_ENTRY	3010		Řádka obsahuje položku seznamu organizačních domén (dirdb)
SO_DIR_ENTRY	3011		Řádka obsahuje položku výpisu organizační domény (dirdb)
SO_DIR_INFO	3012		Řádka obsahuje detailní informace o dirdb záznamu (dirdb)
SO_GATH_ENTRY	3013		Řádka obsahuje položku seznamu gathererů
SO_HEADING	3014		Řádka obsahuje záhlaví výpisu (např. seznamu gathererú)
SO_FILTER	3015		Řádka obsahuje položku seznamu filtrů - popis filtru
SO_SHUTDOWN	3016	Server shut down
SO_REPORT_NAME	3017		Řádka obsahuje položku seznamu reportů
SO_REPORT_PULSE_COST	3018		Řádka obsahuje cenu pulzu v reportu
SO_REPORT_LINE	3019		Řádka obsahuje řádku definice reportu
SO_CALL_DATA	3020		Řádka obsahuje záznam o hovoru (používá se pro synchronizaci dvou Calom serverů)
SO_REPORT_RESULT	3021		Řádka obsahuje řádku výstupu reportu
SO_CALL_DATA_DAY	3022		Řádka obsahuje záznam o začátku nového dne (používá se pro oddělení řádků SO_CALL_DATA)
SO_PROCESSING_REPORT	3023	Report in progress...
SO_LOCAL_TIME	3024		Řádka obsahuje informaci o času serveru
SO_VERSION	3025		Řádka obsahuje informaci o verzi serveru
SO_UPTIME	3026		Řádka obsahuje informaci o času uptime serveru
SO_IMPOSVER	3027		Řádka obsahuje informaci o verzi IMPOS systému
SO_LOGGING	3028	<typ ("Console" nebo "Logfile")>: DEBUG=<číslo> INFO=<číslo> LOG=<číslo> AUTH=<číslo>, WARN=<číslo>, AUTHFAIL=<číslo>, ERR=<číslo>, SYS=<číslo>, FATAL=<číslo>, PANIC=<číslo>	Řádka obsahuje informaci o nastavených úrovních jednotlivých hlášení do log souboru
SO_WHO	3029	<uživ. jméno>\t<jméno tasku>	Řádka obsahuje informaci o přihlášeném uživateli
SO_CILDIR_STATUS	3030	CIL codes <"contain" nebo "don't contain"> DIR numbers	Řádka obsahuje informaci zda jsou v CIL kódech hledána telefonní čísla
SO_TARIF	3031		Řádka obsahuje informaci o tarifu
SO_TARIF_DUMP	3032		Řádka obsahuje řádku definice tarifu
SO_HELPER	3033		Řádka obsahuje informaci o pomocné aplikaci (tzv. helperu)
SO_HELPER_LIST	3034		Řádka obsahuje položku seznamu helperů
SO_CONFIG_DUMP	3035		Řádka obsahuje řádku konfiguračního souboru
SO_TARIF_FLAG_DUMP	3036		Řádka obsahuje informaci o nastavení tarifu
SO_LICENSE_DUMP	3037	<id>: <popis>	Řádka obsahuje informaci o licenci