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 actual 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.
WebIMAP/WebMail interfaces with the external address book module by spawning the process off and talking to it via it's stdin and stdout.
The purpose of this is to allow people to write external modules which interface between WebIMAP/WebMail and the data base in which 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 an external global address book you will need a line similar to the following in 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 variables are also available to pass into 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 a comment.
ie. +success LDAP External Address Book
Throughout this HTML page there 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 must be supported by the external address book module:
- COMMANDS (Informs the client of 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 administrators to login to add/change the data)
- ALLOW_SET (This is used to determine whether the stated book is allowed to be changed by the user)
- SET (Only accessible by administrators, allows administrators to update data. Determines whether the selected book is allowed to be changed)
If the external address book does not recognize a command, the following response is given:
S: -failed command unknown command '<command>'.
Where everything after the '-failed' is a comment and can be omitted.
The normal sequence with which 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 books available and select one to use. The user of WebMail normally selects the address book. |
| AVAILABLE | Get the fields which are available in the address book so that WebMail can displays these. |
| SEARCH_FIELDS | Get the fields which 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 normal sequence with which 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 books available and select one to use. The user of WebMail normally selects the address book. |
| AVAILABLE | Get the fields which are available in the address book so that WebMail can displays these. |
| SEARCH_FIELDS | Get the fields which 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 used to inform the client what is available. It 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 used 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 and 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 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 labeled differently, 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, no control or extended characters are allowed)
- INTEGER (This is only allowed integer 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 used 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 ignored 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 used to allow the client to perform an external address book search, where the data provided determines the search parameters. The type of data the search label is will depend on how the search field is generated.
- STRING Search allowing '*' and '?' 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)
There are two types of search, these are OR and AND. The way in which the results are determined depends on which is used. Any field label that the program does not know about is ignored.
You can also specify the range of results that you want with a specific number, a range of numbers or 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 asks for only 10 items, but 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 lines, 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 specify which labels they want, in which case you return them 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 used 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, the client MUST send the username before any requests. Otherwise the search request may be ignored. This is to assist in determining 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 used to provide to the client the list of valid address books. This command is not needed if there 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 used to inform the external address book which book it should use. This command is not needed if there 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 admins to login and update/change the available data. Only once a 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 whether 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 administrators 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 provided can be in any order. Any missing field that is stored in the external address book is to presumed to be empty (ie 0 or ""). The value of the fields may have multiple lines, 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.