The following is the protocol to be used to interface WebIMAP/WebMail with any external global address book. This protocol is used to talk to the external program which in turn talks to the actually external address book. For the purpose of this protocol the client is WebIMAP/WebMail and the server is the external address book protocol.
The external address book is a global accessible address book which you can ask for queries. Only the admin can change and/or update the data, and normally does with some other external program. The users can only read the information.
How WebIMAP/WebMail interfaces with the external address book module is spawn the process off and talks to it via it's stdin and stdout.
The purpose of this is so that people can write external modules which does the interface between WebIMAP/WebMail and the data base they have their address book stored. Examples of this would be interfacing to an LDAP address book or maybe a SQL address book.
This feature was added to WebIMAP/WebMail version 2.0g.
* - These commands were added to version 2.0t of WebMail and higher.
To setup WebIMAP/WebMail to use external global address book you need a line simular to the following into the ini file:
external_book ldapbook
Where the external program is called 'ldapbook' and should be located in the template directory. Extra parameters can be also added to this ini setting just by adding the parameters after the name.
ie. external_book ldapbook -user ||user||@||host||
Some template variable are also available to pass in to the external address book these are:
||user|| the username. (fred)
||host|| the host name/ip (1.2.3.4)
||port|| the host port. (143 or 110)
The first response that the external address book module must return is '+success'. Anything after this is comments.
ie. +success LDAP External Address Book
Through out this HTML page their will be references like:
C: .....
and S: .....
Where the 'C' stands for client which is WebIMAP/WebMail, and 'S' is for server which is the external address book module.
These commands that must be supported by the external address book module:
- COMMANDS (Informs the client the complete list of available commands, or checking if a command exists)
- AVAILABLE (Informs the client what fields are available in the address book)
- SEARCH_FIELDS (Informs the client which fields are allowed to be searched on)
- SEARCH (Allows wild card searching of data, this is expected to be fast)
- GET (This command gets the full address record)
- EXIT (This exits the external module)
The following commands are optional:
- USER (Informs the address book who is accessing the database, can be used to restrict access)
- BOOK_LIST (This displays the list of valid address book names and a small description.)
- BOOK_NAME (This tells the program which address book to use)
- ADMIN_LOGIN (allows admin's to login to add/change the data)
- ALLOW_SET (This is used to determine if the stated book is allowed to changed by the user)
- SET (Only accessible by admin's, allows admin's to update data, or if the selected book is allowed to be changed)
Any command that the external address book does not know what it is then the following response is given:
S: -failed command unknown command '<command>'.
Where everything after the '-failed' is a comment and can be omitted.
The normally sequence that WebMail will talk to the external address book module is:
| <connect to external address book module> | |
| COMMANDS | get the commands that this module supports. |
| USER | If the module supports this command this command will be sent. |
| BOOK_LIST/BOOK_NAME | If the module supports this WebMail will get a list of address book available and select on to use. The user of WebMail normally selects the address book. |
| AVAILABLE | Get what fields are available in the address book so that WebMail can displays these. |
| SEARCH_FIELDS | Get what fields are allowed to be search on so that WebMail can layout the search fields. |
| SEARCH/GET | WebMail will then get a list of items using the search fields provided by use and use this to get the addresses to display. |
| EXIT | Once done WebMail will close the external address book. |
The normally sequence that WebMail 2.0t will change data in a address book is:
| <connect to external address book module> | |
| COMMANDS | get the commands that this module supports. |
| USER | If the module supports this command this command will be sent. |
| BOOK_LIST/BOOK_NAME | If the module supports this WebMail will get a list of address book available and select on to use. The user of WebMail normally selects the address book. |
| AVAILABLE | Get what fields are available in the address book so that WebMail can displays these. |
| SEARCH_FIELDS | Get what fields are allowed to be search on so that WebMail can layout the search fields. |
| ALLOW_SET/SET | WebMail will save the fields provided by use to the selected address book if it is allowed to. |
| SEARCH/GET | WebMail will then get a list of items using the search fields provided by use and use this to get the addresses to display. |
| EXIT | Once done WebMail will close the external address book. |
This command is to inform the client what is available. This command can be used to get a complete list of commands or used to check if a specified command is valid. When checking which commands are available the complete list of commands MUST be returned.
The layout of the command being sent is:
C: COMMANDS
or C: COMMANDS <command check>
The layout of the successful response is:
S: <command>,<command>,...
S: +success <num of commands> commands available.
or
S: +success command available.
The layout of the failed response is:
S: -failed command not available.
ie. C: COMMANDS
S: COMMANDS,AVAILABLE,SEARCH_FIELDS,SEARCH,GET,EXIT,USER,ADMIN_LOGIN,SET
S: +success 9 commands available.C: COMMANDS USER
S: +success command available.
C: COMMANDS SUPERUSER
S: -failed command not available.
This is to inform the client what information is available from a get command. This is basically information like:
record_id* - This is the unique id of this message. (must be first)
full_name* - This is the full name of the person.
email_address* - This is the Email address of the user.
last_name
phone_number
date_of_entry
interests ...etc.
NOTE: record_id* - This is a unique id of the messages and is not allowed to change from a single session but can change over multiple sessions. If the program is run twice it does not necessary need to be the same the second time around as the first. This is to allow easier coding of the program.
The data returned are just labels for the actual data, these labels are used in WebIMAP/WebMail. These labels are limited in how they can be named. They are only allowed small letters and underscores. No other characters are allowed.
Some fields are expected by the CGI is to allow easy interface between the external address book and WebIMAP/WebMail internal address book. Theses are the ones with the '*'. If the variables are label differently then changes to WebIMAP/WebMail templates are required to get interfacing to internal address books.
The response from the program is to also inform the client what type of field it is. As this will effect what type of searches are allowed, and also how the data is used. The type of valid data is:
- STRING (Any printable character is allowed, not control or extended characters are allowed)
- INTEGER (This is only allow integers values, ie 0-9 characters only)
- DATE (This is the number of seconds since 1 JAN 1970, and always in GMT time )
The layout of the command being sent is:
C: AVAILABLE
The layout of the successful response is:
S: <label>=<data type>,<label>=<data type>,...
S: <label>=<data type>,<label>=<data type>,...
S: +success <num of labels> available.
There should not be any failed response:
ie. C: AVAILABLE
S: record_id=STRING,full_name=STRING,email_address=STRING,
S: phone_number=STRING,age=INTEGER,date_of_birth=DATE
S: +success 6 available.
This is to inform the client which fields are allowed to be searched on. Commonly this is full_name and email_address. But any field can be setup to allow searching. Only fields that are returned by this command are allowed to be search on. All other fields are ignore by the search command.
The layout of the command being sent is:
C: SEARCH_FIELDS
The layout of the successful response is:
S: <label>=<data type>,<label>=<data type>,...
S: +success <num of labels> available.
There should not be any failed response:
ie. C: SEARCH_FIELDS
S: full_name=STRING,email_address=STRING
S: +success 2 available.
This is to allow the client to perform an external address book search. Where the data provided determines the search parameters. Depending on the type of data the search label is will depend on how the search field is generate.
- STRING Search allowing '*' and '?' are allowed to assist in restricting the search. (ie f?ed, fre*)
- INTEGER A range of integer values is required separated by a '/' (ie 10/23, -10/-5)
- DATE A range of time is required separated by a '/' (ie 0/9909900)
Also there is two types of search these are OR and AND. This depends on how the results are determined. Any field label that the program does not know about is to be ignored.
Also you can provide the range of results that you want. Where the range may specify a certen number a range of number all the numbers.
ie Range Layout: x-y
If x is missing then presume first item, if y missing presume last item.
1- : Means all results.
-10 : Means first 10 results
20-40 : Means display 20, 21,22...40 result.
The layout of the command being sent is:
C: SEARCH <search type> <range> <label>=<search>,<label>=<search>
The layout of the successful response is:
S: record_id,record_id,..
S: +success <num of results*> located.
num of results* - This must return the total number of possible results, NOT the number of results returned. If the search ask for only 10 items, but the search would normally result in 20 then this should display 20.
The layout of the failed response is:
S: -failed no result available.
ie. C: SEARCH OR 1-20 full_name=fre*,email_address=*@1.2.3.4
S: msg_1,msg_2
S: +success 2 located.C: SEARCH AND -20 full_name=fre*,email_address=*@1.2.3.4
S: -failed no result available.
This command is used to get the complete address details on a specified record id. Where the record id has been provided by the search command. The information can be returned in any order. The value of the fields may have multiple line in which case all '\n', '"' and '\' characters are to be encoded as '\' 'n', '\' 'r', '\' '"' and '\' '\'. No '\r' are allowed to be present. The client can also specific which labels that they want, in which case you return then in the order that they asked for them.
The layout of the command being sent is:
C: GET <record id>
or C: GET <record id> <label>[,<label>[,..] ]
The layout of the successful response is:
S: <label>=<value>
S: <label>=<value>
S: <label>=<value>
S: <label>=<value>...
S: +success '<record id>' located.
The layout of the failed response is:
S: -failed no record available.
ie. C: GET msg_1
S: record_id=msg_1
S: full_name=Lynden
S: email_address=lynden@1.2.3.4
S: last_name=
S: phone_number=
S: date_of_entry=90123123
S: interests=computers,programming\ntesting code.
S: +success 'msg_1' located.C: GET msg_1 full_name,email_address
S: full_name=Lynden
S: email_address=lynden@1.2.3.4
S: +success 'msg_1' located.
This command is to exit the external address book.
The layout of the command being sent is:
C: EXIT
The layout of the successful response is:
S: +success bye.
There should not be any failed response:
ie. C: EXIT
S: +success bye.
This command is to inform the external address book who is trying to access the server. This can be entered as a command line parameter as well.
ie. ./book -user username@host
If this command is available then the client MUST sent the username before any requests. Otherwise search request may be ignored. This is to assist in determine which address book to use if multiple address books are available.
The layout of the command being sent is:
C: USER <username@host>
The layout of the successful response is:
S: +success welcome '<username>'.
The layout of the failed response is:
S: -failed not a valid username.
ie. C: USER lynden@1.2.3.4
S: +success welcome 'lynden'.
This command is to provide to the client the list of valid address books. This command is not needed if their is only one address book available. This also provides a small description about the address book.
The layout of the command being sent is:
C: BOOK_LIST
The layout of the successful response is:
S: <address book>=<book description>
S: +success <num of books> address books.
The layout of the failed response is:
S: -failed no valid address books.
ie. C: BOOK_LIST
S: students=This is the list of all students at xxxxx
S: staff=This is the complete list of all staff members.
S: +success 2 address books.
This command is to inform the external address book which book to use. This command is not needed if their is only one address book.
The layout of the command being sent is:
C: BOOK_NAME <address book>
The layout of the successful response is:
S: +success address book '<address book>' selected.
The layout of the failed response is:
S: -failed not a valid address book.
ie. C: BOOK_NAME students
S: +success address book 'students' selected.
This allows admin's to login and update/change the available data. Only once an valid admin_login is done is the SET command allowed to be used.
The layout of the command being sent is:
C: ADMIN_LOGIN <username> <password>
The layout of the successful response is:
S: +success welcome admin.
The layout of the failed response is:
S: -failed not a valid admin.
ie. C: ADMIN_LOGIN test test
S: +success welcome admin.
This command is used to check if an address book is allowed to be changed by the SET command.
The layout of the command being sent is:
C: ALLOW_SET <address book>
The layout of the successful response is:
S: +success you are allowed to be change this address book.
The layout of the failed response is:
S: -failed not allow to change this address book.
ie. C: ALLOW_SET personal
S: +success you are allowed to be change this address book.
This allows admin's to change/add records on the external database. To change a current record you first must do a search command first to get the record_id. To create a new record you do not need to do a search. The information which is provide can be in any order. Any field that is missing that is stored in the external address book is to presume to be empty (ie 0 or ""). The value of the fields may have multiple line in which case all '\n' characters are to be encoded as '\' 'n' and all '\' into '\' '\'. No '\r' are allowed to be present.
NOTE: the 'label' 'record_id' is to be ignored if passed to the program.
The layout of the command being sent is:
C: SET
or C: SET <record_id>then C: <label>=<value>
C: <label>=<value>....end with: C: <empty line>
The layout of the successful response is:
S: +success record add/updated.
The layout of the failed response is:
S: -failed to add/change record.
ie. C: SET
C: full_name=Lynden
C: email_address=lynden@1.2.3.4
C: date_of_entry=90123123
C: interests=computers,programming\ntesting code.
S: +success record add/updated.