Overview The most important file for the author of an application using the c-client is mail.h. mail.h defines several important structures of data which are passed between the main program and the c-client. Although some functions (e.g. mail_fetchtext_body()) return the data fetched, for certain other data items (e.g. flags) you need to get the data as a structure reference. mail.h also defines a large number of useful constants and structures. When a function in mail.h exists to reference data, it MUST be used instead of referencing the structures directly. This is because in some cases the data is not actually fetched until a reference (via the function call) is made. For example, although the MESSAGECACHE element for a message can be obtained by indexing the proper cache element in the stream, there is no guarantee that the item in fact exists unless mail_fetchstructure_full() is called for that message. Less costly functions. also exist to create and load a MESSAGECACHE element. The main program will probably also need to include smtp.h, misc.h, and osdep.h, but this usage should be solely to receive function prototypes. Any other definitions in those files should be considered private to that module. Two important predefined symbols are NIL and T. NIL is any sort of "false"; T is any sort of "true". NIL is also used to null-specify certain optional arguments. * * * IMPORTANT * * * Any multi-threaded application should test stream->lock prior to calling any c-client stream functions. Any attempt to call a mail_xxx() function while one is already in progress on the same stream will cause the application to fail in unpredictable ways. Note that this check is insufficient in a preemptive-scheduling multi-tasking application due to the possibility of a timing race. Such applications must be written so that only one process accesses the stream, or to have a higher level lock. Since MAIL operations will not finish until they are completed, a single-tasking application does not have to worry about this problem, except in the callback invoked from MAIL (e.g. mm_exists(), etc.) in which case the stream is *always* locked.