Structured Information Management Transfer Protocol (SIMTP) definition Version 0.2.1 2006-06-12 MERIGHI Marcus McMer (a) Tor dot AT Changelog: (this is _very_ fragmentary for the early changes!) 2006-07-05 Modified : no numeric id anymore, using sim-id instead. Renamed AttributeType SIMalias to SIMincludeDN and ObjectClass SIMalias to SIMincluder since this by far better describes what it does. 2006-07-04 Lot's of bugfixes to simalias-code. 2006-06-12 Getting work done on "acts" (act-*.inc). Acts (ACT_* in simtpd.conf) can be assigned to ObjectClasses and call response types- and subtypes. Therefore incremented to 0.2.1. 2006-05-28 Finally finished SIMalias, therefore incremented version to 0.2.0. Modified spotsel code to use SIMaliases. SIMalias contains a DN which makes the application server include content from this DN. Added AttributeType SIMinitDN which can be added to ObjectClass SIMperson and makes the DN specified by SIMinitDN the starting point (after welcome message, if activated). Added AttributeType SIMsubsListFilter which can be added to any entry (ObjectClass SIM) and applies the specified filter to sub entries list. In this case there's a new menu entry "Show all sub entries". 2006-05-05 Added [email]||[infos] to / 2006-05-03 Added tag to text/vnd.sim-spotsel 2006-04-27 Added tags and to text/vnd.sim-spotsel, which were already used. 2006-04-25 Added tags , and to text/vnd.sim-spotsel. Added mime type text/vnd.sim-eventlist. Added to text/vnd.sim-areaconf. Added phone and street to . 2006-04-24 Incremented to 0.1.9: Explanation status/task-id. Added "" to text/vnd.sim-areaconf. 2006-04-01 Bad date for serious messages. Incremented version to 0.1.8 to reflect addition of SYST MIME, further modifications on DISP MIME for PDFs: ENCODING, CHARSET, PRINT and renamed text/x-sim-areaconf to text/vnd.sim-areaconf and text/x-sim-spotsel to text/vnd.sim-spotsel. Added USER, PASS, SESS, CLID to this document. Added description of connection setup. Added various examples. Added CREDFAIL and ACCTLOCK. 2006-03-30 Incremented version to 0.1.7 to reflect: DISP MIME for PDFs restructured heavily: added options charset and encoding; FNAME got new special case: "drctprnt" ("direct print"). 2006-02-01 Incremented version to 0.1.6 to reflect introduction of CONT LIST. SRCHRES became TARGET. All TREEVIEW stuff (TREEVIEW, TARGET, EXPAND) moved to CONT MENU. 2006-01-30 Moved various mime types from FORM to DISP; added for text/x-sim-spotsel. 2006-01-22 Incremented version to 0.1.5 because of all the nice new stuff. 2006-01-22 Completed what was already used but not mentioned here. Much work on mime stuff. Removed COLL (replaced by "EXPAND 0"). Added LOGOFF and LOGEDOFF. 2005-12-14 Incremented version to 0.1.4 since there are new options: KEYB, SRCHRES, TREEVIEW, COLL, EXPAND 2005-06-24 Removed WAIT; ``Upgraded'' to 0.1.1. 2005-06-23 Copied example conversation from real daemon output. Yeah! ``Upgraded'' to 0.1.0 since there's something that works. 2005-06-19 Integrated simap Abbriviations: S: Server; C: Client rule 1: Client always answers only! Exceptions: USER, PASS, SESS, CLID, END TRANS. See below. rule 2: if C: speaks without beeing asked, S: has to confirm with same statement. rule 3: every line of communication is prepended with a transaction identifier (tid). These need to be unique. Exception is "0000" which is used if proper creation ot tid is not possible (for instance for error messages). Exceptions: BEGIN, END. These are followed by the tid. rule 4: after S: issues TRANS, only transfers S: to C: of mode "ALRM" are permitted. rule 5: S: only listens when TRANS was sent; otherwise it says "shut up, it's my turn!". - Synopsis: 1) Command Example: USER foobar 2) Command $tid [ Mode ] Type Options Example: BEGIN 1234 1234 1234 1234 END 1234 - Commands: 1) Authentication - Client speaks first. - USER Required on connect. Specifies username. - PASS Required on connect. Specifies passphrase. - CLID Optional on connect. Specifies client identification. Needs to be unique within database. Suggestion: hostname(1). Must precede USER and PASS if used. - SESS Optional on connect. Must precede USER and PASS, if used. Requests re-establishment of old session (for instance after network error). After successful authentication S: responds with "SYST SESS", "SYST LOGOFF" and optional "SYST MIME text/vnd.sim-printers". For details see below. If invalid credentials are provided, S: responds with "CREDFAIL" or ACCTLOCK, if there were too many failed login attempts. 2) Post-Authentication: - BEGIN Starts a transaction type Always followed by an unused (within the session) $tid and a type, optionally followed by (an) option(s). - END Ends a transaction Always followed by the $tid of the transaction that is to be ended. - Modes Since Types are non-ambiguous the Mode can be omitted! - SYST Will be handled between S: and C:, no user interference. Types: - CREDFAIL 'Credentials failed' - invalid USER/PASS. Uses fake tid "0000". specifies remaining tries before account lockout. Example: BEGIN 0000 CREDFAIL 0000 Invalid credentials. You have more tries 0000 before account lockout. END 0000 - ACCTLOCK 'Account locked' - After too many failed login attempts the server locks the account for a certain period and notifies the user. Example: BEGIN 0000 ACCTLOCK 600 simaster@domain.tld 0000 The Account is now locked for 600 seconds. Please 0000 retry later. If you think this is a malfunction, please 0000 contact . END 0000 - SESS Session ID ($sid) negotiation. An extra Type is required since C: might need to know it's about session negotiation and answers without user interaction: a web page, for instance. Used only once at the beginning of a _new_ Session. Example: BEGIN 1234 SYST SESS 1234 3987666 END 1234 - TRANS 'Transfer' - S: tells C: to transfer user input. - QUIET 'Shut up, stupid!' - if C: speaks without S: having sent "TRANS" it gets BEGIN 1234 SYST QUIET HUGE 1234 Shut up stupid, it's my turn END 1234 - LOGOFF Tells client the tid to return to initiate logoff. Example: BEGIN 1234 SYST LOGOFF 1234 474623 END 1234 - LOGEDOFF Tells client that there has been a regular (as opposed to eg. network problems) logoff. Example: BEGIN 208853 SYST LOGEDOFF [no content!] END 208853 - MIME 'mime type' - contains lines which have a special format. Options: - text/vnd.sim-printers 'functional printer to real printer assignments' - |||| ||label-printer||hp-laserjet-1200||\n - CONT 'Container' Types: - SUBM 'Submit' This container type surrounds one or more FORM entries. It tells the client to transfer all surrounded FORM entries when TRANS is issued by S: - PULL 'Pulldown' lets user select among given entries. - MENU Lets user select among given entries in a 'menu' style. Only one item can be selected, action is triggered on selection action. Options: - KEYB "a" Client should make menu entry triggered by control key (i386: ctrl) plus the key following "KEYB". - TREEVIEW 'tree view' - make a tree of the entries. Useful for pathed entries (_not_ container PATH!). - EXPAND 0|1|2|N|ALL [TREEVIEW] 'expand tree' - expand as many hirarchy levels as stated after "EXPAND" in TREEVIEW. - OID 0.1.2.3 [TREEVIEW] - TARGET [TREEVIEW] "Search Result" indicates that this entry has to be pointed out. Useful, if pathed entries are used and therefore not all container entries are of interest (apart from telling the user where she is navigating). May occurr multiple in one container. - PATH Surrounds selection elements and should be displayed in a distinguishable way. - LIST Contains selection elements which can be selected and are sent when the required submit button is triggered (or a double click - or whatever trigger action - happens). Options: - MULTI User may select more then one item. The item should therefore be displayed with more than one option visible. The selected items must be return by the client to the server each on a line, prepended by the tid. What a surprise. - ROWS [1|2|N|ALL] Tells the client how many rows to display. - FORM User will have to interact by supplying or selecting data. The data given by the user has therefore to be returned to S: Types: - SEL 'Selection' - User has choice between given options What user sees (and chooses) is not, what is transfered; in this case $tid is followed by a whitespace, an id a whitespace and the text to show. Options: - NOMOD 'No modify' - tells C: to show- but not to make editable. - SELECTED 'Selected' - tells C: to show this entry as selected. - INPUT options - STR 'String' - User has to use his/her keyboard! Options: - NOMOD 'No modify' - tells C: to show- but not to make editable. - PWD 'Password' - tells C: to not to print or mask what user types. - CAL 'Calendar' - SIZE options - INPUT options - BIN 'Binary' - User has to supply some binary data, like a file. - MIME 'mime type' - contains lines which have a special format. Options: - text/vnd.sim-eventlist 'Event list' - list of relevant events. ||[label]||[dn]||\n - text/vnd.sim-areaconf 'Area configuration': ||[id]||[koord-x]||[koord-y]||[row#]||[spot#]||\ [group]||[status]||[info]||\n ||[width]||[height]||\n ||[id]||[displayname (description)]||\n ||[id]||[label]||\n - text/vnd.sim-spotsel: s: -> c: ||[id]||[koord-x]||[koord-y]||[row#]||[spot#]||\ [group]||[status]||[info]||[discount-id]||\ [task]||[person-id]||[creator-id]||\ [modifier-id]||[create-datetime]||\ [modify-datetime]||[required-input]||\n ([task]: 0 = not current, 1 = current, 2 = printed, additive) ||[sim-id]||[label]||[required-input-A&&\ required-input-B]||\n ||[discount-id]=[discount-label]||\ [pricegroup-id]=[pricegroup-label]||[price]||\n ||[date/time]||\n ||[label]||\n ||[person-id]||[label]||[surname]||[givenname]||[zip]||\ [phone]||[street]||[birthyear]||[email]||[infos]||\n ||[spot-id]||[date/time]||[task-id]||[person-id]||\n ||[sim-id]||[label]||[current-val]||\n Explanation status/task-id: 0=none, 1=process,\ 2=booked, 3=sold, 4=canceled, 5=locked,\ 20=discount changed, 21=printed. ||[sale|book|cancel]||\n ||[events|sales|bookings|cancellations]||\n ||[surname]||[givenname]||[zip]||[phone]||\ [street]||[birthyear]||[numberOfSpots]||\ [sortNumber]||[dn]||\n c: -> s: ||[id]||[koord-x]||[koord-y]||[row#]||[spot#]||\ [group]||[status]||[info]||[disount-id]||\ [required-input]||\n ||[sim-id]||[label]||[mod 0|1]||\n ||[spot-id]||[status-id]||\n ||[empty]||\n ||[empty]||\n ||[surname]||[givenname]||[zip]||[phone]||\ [street][birthyear]||[email]||[infos]\n ||[empty]||\n ||[empty]||\n ||[empty]||\n ||[surname]||[givenname]||[zip]||[phone]||\ [street]||[birthyear]||[numberOfSpots]||\ [sortNumber]||[dn]||\n - FNAME foobar.baz 'File name' - suggested file name if it is saved to local file system. - DISP User will be presented some data, no input required and allowed by user. The focus of the types and options is formatting and display of information. There should be more meta information usable to the client. This means more types an options, though. Types: - MIME 'mime type' - contains lines which have a special format. Options: - application/vnd.sim-pdf This is PDF content - text/tab-separated-values These are tab seperated values - CHARSET iso-8859-1 'character set' - specifies charset of the content. If not specified, iso-8859-1 is to be assumed. - ENCODING base64 'encoding' - specifies the encoding used for transport; the client has to decode before further processing. If not specified, 'none' is to be assumed. Possible values are: base64. - FNAME foobar.baz 'File name' - suggested file name if it is saved to local file system. - PRINT 'print directly' - do not call display programm but print directly to printer specified. For assignment of functional- to real printer see SYST MIME text/vnd.sim-printers. If no local- printername is specified, client machine default printer is to be assumed. - TEXT 'Text' Options - CAL 'Calendar' - Size Options - IMAG 'Image' Options - JPG - GIF - PNG - PDF 'Portable Document Format (sic! ;-)'. - CAPT 'Caption' Options - Size Options - Hirarchy Options - DESC 'Description'. This is not "core" information and thus not required to to the job. But yet it is always displayed. Somewhere between caption and help. Options - Size Options - HELP Not necessarely displayed right from the start. May be just a user selectable area which triggers display of the helping information. Options: - Size Options - WARN - ERROR An error message; Options: - Size Options - X-FOOBAR Custom Type; SITP will never use X-* by protocol! But yet such Types should honor the rule of "Types are non- ambiguous", which implies writing an e-mail to simtp (at) tor (dot) at if you use one. - ALRM Intended for use after TRANS if S: has to say something really important. May use special $tid of "0000", for instance with DBMYSQL, since this prevents creation of unique $tid. - DISC 'Disconnect' - Disconnection message; _must_ provide remaining time before disconnection. - UNKNOWN 'unknown' - An unknown error occurred. - SEC 'Security' - Security alerts. - PROTO 'Protocol error' - DATA 'Data' - Some data (management) error. - CONF 'config' - something was found in an un- or misconfigured state. - DBLDAP 'ldap database' - DBMYSQL 'mysql database' - X-BARFOO 'X-*' is meant for private use. - Options Groups These are refered to from above as a group instead of mentioning each option multiple times. These are just relative and real sizes in inches/mm depend on the client (html-o-phil)! - SIZE Options - TINY - SMALL - MEDIUM - Default - BIG - HUGE - INPUT Options - REQ (required) - OPT (optional) - HIRARCHY Options - H1 (highest level) - H2 - H3 - H4 - H5 (lowest level) - FORMAT options: - BGC - Background colour - TXTC - Text colour Example Conversation C: SESS sid-000 C: CLID fallera.foo.bar C: USER FOOBAR C: PASS S0mTH1ng S: BEGIN 465313 SYST SESS S: 465313 699437 S: END 465313 S: BEGIN 608879 SYST LOGOFF S: 608879 351885 S: END 608879 S: BEGIN 839035 SYST MIME text/vnd.sim-printers S: 839035 ||label-printer||hp-laserjet-1200||\n S: 839035 ||ticket-printer||ticketer-500||\n S: END 839035 S: BEGIN 828827 FORM SEL MENU TINY S: 828827 Dienste S: END 828827 S: BEGIN 538754 FORM SEL MENU TINY S: 538754 Gruppen S: END 538754 S: BEGIN 244424 FORM SEL MENU TINY S: 244424 Immobilien S: END 244424 S: BEGIN 275109 FORM SEL MENU TINY S: 275109 Mobilien S: END 275109 S: BEGIN 324628 FORM SEL MENU TINY S: 324628 Personen S: END 324628 S: BEGIN 674859 FORM SEL MENU TINY S: 674859 Server S: END 674859 S: BEGIN 217818 CONT SUBM S: BEGIN 91589 FORM STR SMALL S: 91589 Suchbegriff S: END 91589 S: END 217818 S: BEGIN 925551 SYST TRANS C: 91589 Pers* C: END 925551 S: END 925551 S: BEGIN 997511 FORM SEL MENU TINY S: 997511 Personen S: END 997511 S: BEGIN 448590 SYST TRANS C: 997511 Personen C: END 448590 S: END 448590 S: BEGIN 796537 FORM SEL MENU SMALL S: 796537 Marcus Merighi S: END 796537 S: BEGIN 812555 SYST TRANS C: 244424 Immobilien C: END 812555 S: END 812555 S: BEGIN 25664 FORM SEL MENU SMALL S: 25664 Theater Phoenix LINZ S: END 25664 S: BEGIN 401719 SYST TRANS S: BEGIN 495019 ALRM PROTO S: 495019 prot_sep missing S: END 495019