home *** CD-ROM | disk | FTP | other *** search
/ vsiftp.vmssoftware.com / VSIPUBLIC@vsiftp.vmssoftware.com.tar / FREEWARE / FREEWARE40.ZIP / pine / c-client / internal.doc < prev    next >
Text File  |  1994-01-09  |  41KB  |  865 lines
  1.       Documentation of C-client Functions and Interfaces
  2.  
  3.                  Mark Crispin
  4.              Revised 18 June 1992
  5.  
  6.                  Introduction
  7.  
  8.      The C-client API was originally written at Stanford University as
  9. a set of routines to support IMAP and SMTP from a main program which
  10. would handle the user interface.  A sample main program which uses the
  11. C-client, MTEST.C, has run on a wide variety of platforms including
  12. Unix, TOPS-20, Macintosh, and MS-DOS.
  13.  
  14.      This is a major redesign of the original C-client by the original
  15. author, made at the University of Washington.  It uses ANSI C calling
  16. conventions throughout to assist in function argument type checking.
  17. It also provides the capability of having multiple means of accessing
  18. mail through the user of "drivers"; consequently, in addition to
  19. supporting IMAP it also supports Berkeley (/usr/spool/mail), Tenex
  20. (mail.txt), mbox, mh, and netnews.  A future version of the C-client
  21. will probably convert the current direct usage of SMTP to a driver as
  22. well.
  23.  
  24.      C-client also supports MIME, the Internet Proposed Standard for
  25. multi-part typed message bodies.
  26.  
  27.      The most important file for the author of an application using
  28. the C-client is MAIL.H.  MAIL.H defines several important structures
  29. of data which are passed between the main program and the C-client.
  30. Although some functions (e.g. mail_fetchtext()) return the data
  31. fetched as a convenience, for some data items (e.g. flags) you need to
  32. get the data as a structure reference.  MAIL.H also defines a number
  33. of useful constants.
  34.  
  35.      It should be noted that when MAIL functions exist to reference
  36. data they should be used in preference to referencing the structures
  37. directly.  This is because in some cases the data is not actually
  38. fetched until a reference (via the function call) is made.  For
  39. example, although the MESSAGECACHE item for a message can be obtained
  40. by indexing the proper cache element in the stream, there is no
  41. guarantee that the item in fact exists unless mail_fetchstructure() is
  42. called for that message.  Less costly functions, mail_fetchfast() and
  43. mail_fetchflags(), also exist to create and load a MESSAGECACHE item,
  44. but their usage is not recommended except in particular circumstances.
  45.  
  46.      The main program will probably also need to include SMTP.H,
  47. MISC.H, and OSDEP.H, but this usage should be solely to receive
  48. function prototypes.  Any other definitions in those files should be
  49. considered private to that module.
  50.  
  51.                I. Public interface
  52.  
  53.      The files listed in this section are the standard C-client
  54. mailsystem library modules, and are operating system and machine
  55. independent.  Only those functions suitable for external callers are
  56. documented here; other functions are for internal use only and are
  57. used by external callers at their own risk!
  58.  
  59. [MAIL.C]:    Mail Access functions
  60.  
  61. [Note!!  There is an important difference between a "sequence" and a
  62.  "msgno".  A sequence is a string representing one or more messages in
  63.  IMAP2-style sequence format ("n", "n:m", or combination of these delimited
  64.  by commas), whereas a msgno is an int representing a single message.]
  65.  
  66. void mail_link (DRIVER *driver)
  67.  This function adds the specified driver to the list of mail drivers.
  68. Initially there are no drivers, so all programs which intend to use
  69. the MAIL routines need to have at least one call to this function.  A
  70. function which uses IMAP2 would have a statement such as:
  71.   mail_link (&imapdriver);    /* link in IMAP driver */
  72. early in the program's initialization.
  73.  
  74. void mail_find (MAILSTREAM *stream,char *pat);
  75.  This function finds known mailboxes that match the given wildcard
  76. pattern.  The application's mm_mailbox() function is called for each
  77. matching mailbox.
  78.  
  79. void mail_find_bboards (MAILSTREAM *stream,char *pat);
  80.  This function finds known bboards that match the given wildcard
  81. pattern.  The application's mm_bboard() function is called for each
  82. matching mailbox.
  83.  
  84. MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options)
  85.  This function opens the mailbox and if successful returns a stream
  86. suitable for use by the other MAIL functions.  If oldstream is
  87. non-NIL, an attempt is made to reuse oldstream as the stream for this
  88. mailbox.  The options are a bit mask with one or more of the following:
  89.     OP_DEBUG    Log IMAP protocol telemetry through mm_debug()
  90.     OP_READONLY    Open mailbox read-only.
  91.     OP_ANONYMOUS    Don't use or update a .newsrc file for news.
  92.     OP_SHORTCACHE    Don't cache envelopes or body structures
  93.     OP_SILENT    Don't pass mailbox events (internal use only)
  94.  NIL is returned if this function fails for any reason.
  95.  
  96. MAILSTREAM *mail_close (MAILSTREAM *stream)
  97.  This function closes the MAIL stream and frees all resources
  98. associated with it that it may have created (subject to any handles
  99. existing).
  100.  This function always returns NIL, so it can be used as:
  101.     stream = mail_close (stream);
  102.  
  103. MAILHANDLE *mail_makehandle (MAILSTREAM *stream)
  104.  This function creates and returns a handle to the stream, suitable
  105. for use as a secondary copy of the stream.  This is useful when some
  106. entity that wishes to access the stream may survive the stream without
  107. knowing that it outlived it.  For example, an object reading a message
  108. may have a handle to a stream, but the message selection object that
  109. spawned it (and which owns the stream) may have gone away.  A stream
  110. can be closed or recycled while handles are pointing at it, but it is
  111. not completely freed until all handles are gone.  A stream may have an
  112. arbitrary number of handles.
  113.  
  114. void mail_free_handle (MAILHANDLE **handle)
  115.  This function frees the handle and notifies the stream that it has
  116. one fewer handle.  If this is the last handle on the stream and the
  117. stream has been closed, then the stream is freed.
  118.  
  119. MAILSTREAM *mail_stream (MAILHANDLE *handle)
  120.  This function returns the stream associated with the handle if and
  121. only if the stream still represents the same MAIL connection associated
  122. with the handle.  Otherwise, NIL is returned (meaning that there is no
  123. active stream associated with this handle).
  124.  
  125. void mail_fetchfast (MAILSTREAM *stream,char *sequence)
  126.  This function causes a cache load of all the "fast" information
  127. (internal date, RFC 822 size, and flags) for the given sequence.
  128. Since all this information is also fetched by mail_fetchstructure(),
  129. this function is generally not used unless the OP_SHORTCACHE option
  130. in the mail_open() call is used.
  131.  
  132. void mail_fetchflags (MAILSTREAM *stream,char *sequence)
  133.  This function causes a fetch of the flags for the given sequence.
  134. This main reason for using this function is to update the flags in the
  135. local cache in case some other process changed the flags (multiple
  136. simultaneous write access is allowed to the flags) as part of a "check
  137. entire mailbox" (as opposed to "check for new messages") operation.
  138.  
  139. ENVELOPE *mail_fetchstructure (MAILSTREAM *stream,long msgno,BODY **body)
  140.  This function causes a fetch of all the information (envelope,
  141. internal date, RFC 822 size, flags, and body structure) for the given
  142. msgno and, in the case of IMAP, up to MAPLOOKAHEAD (a parameter in
  143. IMAP2.H) subsequent messages which are not yet in the cache.  No fetch
  144. is done if the envelope for the given msgno is already in the cache.
  145. The ENVELOPE and the BODY for this msgno is returned.  It is possible
  146. for the BODY to be NIL, in which case no information is available about
  147. the structure of the message body.
  148.  This is the primary function for fetching non-text information about
  149. messages, and should be called before any attempt to reference cache
  150. information about this message via mail_elt().
  151.  
  152. char *mail_fetchheader (MAILSTREAM *stream,long msgno)
  153.  This function causes a fetch of the complete, unfiltered RFC 822
  154. format header of the specified message as a text string and returns
  155. that text string.
  156.  This function always returns a valid string pointer; if no header
  157. exists or if it can not be fetched (e.g. by a deceased IMAP stream)
  158. an empty string is returned.
  159.  
  160. char *mail_fetchtext (MAILSTREAM *stream,long msgno)
  161.  This function causes a fetch of the non-header text of the specified
  162. message as a text string and returns that text string.  No attempt is
  163. made to segregate individual body parts.
  164.  This function always returns a valid string pointer; if no header
  165. exists or if it can not be fetched (e.g. by a deceased IMAP stream)
  166. an empty string is returned.
  167.  
  168. char *mail_fetchbody (MAILSTREAM *stream,long m,char *sec,unsigned long *len)
  169.  This function causes a fetch of the particular section of the body of
  170. the specified message as a text string and returns that text string.
  171. The section specification is a string of integers delimited by period
  172. which index into a body part list as per the IMAP2bis document.  The
  173. length of the body part, which may not necessarily be null-terminated,
  174. is returned in len.  Body parts are not decoded by this function; see
  175. rfc822_base64() and rfc822_quotedprintable().
  176.  This function may return NIL on error.
  177.  
  178. void mail_fetchfrom (char *s,MAILSTREAM *stream,long msgno,long length)
  179.  This function writes a "from" string of the specified length for the
  180. specified message, suitable for display to the user in a menu line,
  181. into the string pointed to by s.
  182.  If the personal name of the first address in the envelope's from item
  183. is non-NIL, it is used; otherwise a string is created by appending the
  184. mailbox of the first address, an "@", and the host of the first
  185. address.  The string is trimmed or padded with trailing spaces as
  186. necessary to make its length match what the caller requested.
  187.  The length argument is provided to make it convenient for the
  188. application to decide upon the length it wants.  The string s must, of
  189. course, be at least of this length.
  190.  
  191. void mail_fetchsubject (char *s,MAILSTREAM *stream,long msgno,long length)
  192.  This function returns a "subject" string of the specified length for
  193. the specified message, suitable for display to the user in a menu
  194. line.
  195.  The envelope's subject item is copied and trimmed as necessary to
  196. make its length be no more what the caller requested.  Unlike
  197. mail_fetchfromstring(), this function can return a string of shorter
  198. length than what the caller requested.
  199.  The length argument is provided to make it convenient for the
  200. application to decide upon the length it wants.  The string s must, of
  201. course, be at least of this length.
  202.  
  203. LONGCACHE *mail_lelt (MAILSTREAM *stream,long msgno)
  204.  This function returns a `long' cache entry, consisting of an elt (as
  205. a structure, not a poiner), an envelope pointer, and a body pointer.
  206. This is generally used in conjunction with the elt lock count
  207. functionality, to allow an application to associate the cached data of
  208. a message with an open window independent of subsequent C-client
  209. operations.  It is therefore only needed by sophisticated applications.
  210.  Although this function will create a cache entry if it does not
  211. already exist, that functionality is for internal use only.  This
  212. function should never be called without having first called
  213. mail_fetchfast() or mail_fetchstructure() on the message first.
  214.  
  215. MESSAGECACHE *mail_elt (MAILSTREAM *stream,long msgno)
  216.  This function returns the cache entry for the specified message.
  217.  Although this function will create a cache entry if it does not
  218. already exist, that functionality is for internal use only.  This
  219. function should never be called without having first called
  220. mail_fetchfast() or mail_fetchstructure() on the message first.
  221.  
  222. void mail_setflag (MAILSTREAM *stream,char *sequence,char *flag)
  223.  This function causes a store to add the specified flag to the flags
  224. set for the messages in the specified sequence.  If there is any
  225. problem in setting flags, a message will be passed to the application
  226. via the mm_log() facility.
  227.  
  228. void mail_clearflag (MAILSTREAM *stream,char *sequence,char *flag)
  229.  This function causes a store to delete the specified flag from the
  230. flags set for the messages in the specified sequence.  If there is any
  231. problem in clearing flags, a message will be passed to the application
  232. via the mm_log() facility.
  233.  
  234. void mail_search (MAILSTREAM *stream,char *criteria)
  235.  This function causes a mailbox search using the specified criteria
  236. (in IMAP2 format).  The application's mm_searched() function is called
  237. for each message that matches the search criteria.  If there is any
  238. problem in searching, a message will be passed to the application via
  239. the mm_log() facility.
  240.  
  241. long mail_ping (MAILSTREAM *stream)
  242.  The function pings the stream to see if it is still active.  It may
  243. cause an "implicit check" for new mail.  It returns T if the stream is
  244. still alive, NIL otherwise.
  245.  
  246. void mail_check (MAILSTREAM *stream)
  247.  This function causes an explicit check of the mailbox for new
  248. messages including a remote reparse of all flags in the mailbox.  The
  249. application's mm_exists() function is called with the number of
  250. messages in the mailbox.  The status of the check is passed to the
  251. application via the mm_log() facility.
  252.  Note that mail_fetchflags() needs to be called to update the flags in
  253. the local cache if there was a remote change.
  254.  
  255. void mail_expunge (MAILSTREAM *stream)
  256.  This function causes an expunge of the mailbox.  The application's
  257. mm_expunged() function is called for each message that has been
  258. expunged.  The application's mm_exists() function is called at the
  259. start and end of the expunge to ensure synchronization.  The status of
  260. the expunge is passed to the application via the mm_log() facility.
  261.  Note that the decrementing of msgno's for subsequent messages happens
  262. immediately; for example, if three consequtive messages starting at
  263. msgno 5 are expunged, mm_expunged() will be called with a msgno of 5
  264. three times.
  265.  
  266. long mail_copy (MAILSTREAM *stream,char *sequence,char *mailbox)
  267.  This function causes the messages in the specified sequence to be
  268. copied to the specified mailbox.  The system \Seen flag is set for
  269. these messages and T is returned if the copy is successful.
  270.  If there is any problem in copying, a message will be passed to the
  271. application via the mm_log() facility and the function returns NIL.
  272. No copying is actually done in this case.
  273.  Note that the mailbox must be on the same host as the stream and is a
  274. mailbox of the type of the source mailbox only.
  275.  
  276. long mail_move (MAILSTREAM *stream,char *sequence,char *mailbox)
  277.  This function causes the messages in the specified sequence to be
  278. copied to the specified mailbox.  The system \Seen and \Deleted flags
  279. are set for these messages and T is returned if the copy is successful.
  280.  If there is any problem in copying, a message will be passed to the
  281. application via the mm_log() facility and the function returns NIL.  No
  282. moving is actually done in this case.
  283.  Note that the mailbox must be on the same host as the stream and is a
  284. mailbox of the type of the source mailbox only.
  285.  
  286. void mail_gc (MAILSTREAM *stream,long gcflags)
  287.  This function purges the cache of entries of a specific type.  Some
  288. drivers do not allow purging of particular cache types, and an attempt
  289. to do so is ignored.  The gcflags argument is a bit mask composed of
  290. the following values:
  291.     GC_ELT        message cache elements (IMAP2 driver only)
  292.     GC_ENV        ENVELOPEs and BODYs
  293.     GC_TEXTS    cached texts (IMAP2, MH, and NEWS drivers only)
  294.  
  295. char *mail_date (char *string,MESSAGECACHE *elt)
  296.  This function writes into string a date/time in the form
  297.     dd-mmm-yyyy hh:mm:ss +zzzz
  298. based based upon the data in the elt.  The string must be large enough
  299. to hold this string.
  300.  
  301. long mail_parse_date (MESSAGECACHE *elt,char *string);
  302.  This function parses the date/time stored in the given string and
  303. stores the result of the parse in the elt.  If the parse is successful,
  304. T is returned, else NIL.
  305.  
  306. void mail_debug (MAILSTREAM *stream)
  307.  This function enables telemetry logging for this stream.  All
  308. telemetry is passed to the application via the mm_dlog() facility.
  309.  
  310. void mail_nodebug (MAILSTREAM *stream)
  311.  This function disables telemetry logging for this stream.
  312.  
  313. ENVELOPE *mail_newenvelope ()
  314.  This function returns a new, empty envelope.
  315.  
  316. ADDRESS *mail_newaddr ()
  317.  This function returns a new, empty address.
  318.  
  319. BODY *mail_newbody ()
  320.  This function returns a new, empty body.
  321.  
  322. PARAMETER *mail_newbody_parameter ()
  323.  This function returns a new, empty body parameter.
  324.  
  325. PART *mail_newbody_part ()
  326.  This function returns a new, empty body part.
  327.  
  328. void mail_free_body (BODY **body)
  329.  This function frees a body and all its contents.
  330.  
  331. void mail_free_body_parameter (PARAMETER **parameter)
  332.  This function frees a body parameter and all its contents.
  333.  
  334. void mail_free_body_part (PART **part)
  335.  This function frees a body part and all its contents.
  336.  
  337. void mail_free_elt (MESSAGECACHE **elt)
  338.  This function frees a cache element.  Normally, this is used only if
  339. the main program has a private pointer to cache elements.  If so, it
  340. is expected to increment the cache element's lockcount when it makes a
  341. private pointer, and to call this function when it is finished with it.
  342.  
  343. void mail_free_lelt (LONGCACHE **lelt)
  344.  This function frees a long cache element.  Normally, this is used only if
  345. the main program has a private pointer to cache elements.  If so, it
  346. is expected to increment the cache element's lockcount when it makes a
  347. private pointer, and to call this function when it is finished with it.
  348.  
  349. void mail_free_envelope (ENVELOPE **env)
  350.  This function frees an envelope and all its contents.
  351.  
  352. void mail_free_address (ADDRESS **address)
  353.  This function frees an address and all its contents.
  354.  
  355. [MISC.C]:    Miscellaneous utility functions
  356.  
  357. char *ucase (char *string)
  358.  This function converts each lowercase character of the specified
  359. string to uppercase and returns the string.
  360.  
  361. char *lcase (char *string)
  362.  This function converts each uppercase character of the specified
  363. string to lowercase and returns the string.
  364.  
  365. char *cpystr (char *string);
  366.  This function returns a copy of the string.
  367.  
  368. long find_rightmost_bit (long *valptr)
  369.  This function returns -1 if the 32-bit value pointed to by valptr is
  370. non-zero, otherwise it returns the bit number (0 = LSB, 31 = MSB) of
  371. the right-most bit in that value.  This is used to convert from the
  372. bits in the cache's userFlags item to an index into the stream's
  373. userFlags array of flag texts.
  374.  
  375. long min (long i,long j)
  376.  This function returns the minimum of the two integers.
  377.  
  378. long max (long i,long j)
  379.  This function returns the maximum of the two integers.
  380.  
  381. long search (char *s,long c,char *pat,long patc)
  382.  This function does a fast case-independent search for the given
  383. pattern in pat (lenth patc) in base string s, and returns T if the
  384. pattern is found in the string.
  385.  
  386. long pmatch (char *s,char *pat)
  387.  This function returns T if the given wildcard pattern matches the
  388. string in s.  Otherwise NIL is returned.
  389.  
  390. [SMTP.C]:    Mail Transfer Protocol functions
  391.  
  392. SMTPSTREAM *smtp_open (char **hostlist,long debug)
  393.  This function opens an MTP connection to a one of the hosts in the
  394. host list and if successful returns a stream suitable for use by the
  395. other MTP functions.  The hosts are tried in order until a connection
  396. is successfully opened.  If debug is non-NIL, mtp_debug() is called on
  397. the stream immediately after the TCP connection is opened so that the
  398. greeting and hello protocol goes into the debugging telemetry.  NIL is
  399. returned if this function fails to open a connection to any of the
  400. hosts in the list.
  401.  
  402. void smtp_close (SMTPSTREAM *stream)
  403.  This function closes the MTP stream and frees all resources
  404. associated with it that it may have created.
  405.  
  406. long smtp_mail (SMTPSTREAM *stream,char *type,ENVELOPE *msg,BODY *body)
  407.  This function negotiates an MTP transaction of the specified type
  408. (one of "MAIL", "SEND", "SAML", or "SOML") to deliver the specified
  409. message.  This function returns T if success or NIL if there is any
  410. failure.  The text reason for the failure is in the stream's reply
  411. item; if it is associated with a recipient it is also in that address'
  412. error item.
  413.  
  414. void mtp_debug (SMTPSTREAM *stream)
  415.  This function enables SMTP protocol telemetry logging for this
  416. stream.  All SMTP protocol operations are passed to the application
  417. via the mm_dlog() facility.
  418.  
  419. void mtp_nodebug (SMTPSTREAM *stream)
  420.  This function disables SMTP protocol telemetry logging for this
  421. stream.
  422.  
  423. [RFC822.C]:    RFC 822 Protocol support functions
  424.  
  425. [Only the functions documented here should be used by application
  426.  programs.]
  427.  
  428. void rfc822_header (char *header,ENVELOPE *env,BODY *body)
  429.  This function writes an RFC 822 format header into header based on
  430. the information in message.
  431.  
  432. void rfc822_write_address (char *destination,ADDRESS *address)
  433.  This function writes an RFC 822 format address list into destination
  434. based on the information in address and is therefore the inverse of
  435. rfc822_parse_adrlist().
  436.  
  437. void rfc822_parse_msg (ENVELOPE **en,BODY **bdy,char *s,unsigned long i,
  438.                STRING *b,char *host,char *tmp)
  439.  This function parses the RFC 822 header pointed to by s with body
  440. pointed to by stringstruct b into the specified destination
  441. envelope and body pointers, using host as the default host name and
  442. tmp as a scratch buffer.  This function is intended solely to support
  443. header parsing for non-IMAP MAIL drivers.  Any parsing errors are
  444. noted via the mm_log() mechanism.
  445.  
  446. void rfc822_parse_adrlist (ADDRESS **lst,char *string,char *host)
  447.  This function parses the address list in the given string into an
  448. address list in lst.  Any addresses missing a host name are have the
  449. host name defaulted from the host argument.  If the destination list
  450. is non-empty it appends the new addresses to the list.  Any parsing
  451. errors are noted via the mm_log() mechanism.
  452.  
  453. long rfc822_output (char *t,ENVELOPE *env,BODY *body,soutr_t f,TCPSTREAM *s)
  454.  This function writes the message described with the given envelope
  455. and body, using the I/O function f and passing f the designator s.
  456. The first argument, t, is a scratch buffer which must be large
  457. enough to hold the message header.  T is returned if this function
  458. succeeds, else NIL is returned.
  459.  The function f is of the form:
  460.   typedef long (*soutr_t) (void *stream,char *string);
  461. where stream is intended to hold sufficient information to enable the
  462. output routine to know where to output to, and the string is a null-
  463. terminated string to output.  This function returns either T or NIL,
  464. and that value is passed up to rfc822_output() for its return.
  465.  
  466. void *rfc822_base64 (char *src,unsigned long srcl,unsigned long *len)
  467.  This function decodes a BASE64 body part given a source string and
  468. its length.  The decoded body part as a sequence of binary bytes is
  469. returned, and its length is returned in len.
  470.  
  471. char *rfc822_qprint (char *src,unsigned long srcl,unsigned long *len)
  472.  This function decodes a Quoted-Printable body part given a source
  473. string and its length.  The decoded body part as an 8-bit character
  474. string is returned, and its length is returned in len.
  475.  
  476.              II. Main program co-routines
  477.  
  478.      All main programs which use the C-client must have the following
  479. service co-routines:
  480.  
  481. [Main program]
  482.  
  483. #include "mail.h"
  484. #include "smtp.h"
  485. #include "misc.h"
  486. #include "osdep.h"
  487.  
  488. void mm_searched (MAILSTREAM *stream,long number)
  489.  This function is called from mail_search to notify the main program
  490. that this message number matches the search.  Note that the stream is
  491. locked and that therefore you cannot call any mail_xxx functions!
  492.  
  493. void mm_exists (MAILSTREAM *stream,long number)
  494.  This function is called from several functions to notify the main
  495. program that there are this many messages in the mailbox.  It is also
  496. used to notify the main program of new mail, by announcing a higher
  497. number than the main program was previously aware.  Note that the
  498. stream is locked and that therefore you cannot call any mail_xxx
  499. functions!
  500.  
  501. void mm_expunged (MAILSTREAM *stream,long number)
  502.  This function is called from mail_expunge to notify the main program
  503. that this message number has been expunged from the mail file and that
  504. all subsequent messages are now referenced by a message number one
  505. less than before.  This implicitly decrements the number of messages
  506. in the mailbox.  Note that the stream is locked and that therefore you
  507. cannot call any mail_xxx functions!
  508.  
  509. void mm_mailbox (char *string)
  510.  This function is called from mail_find to notify the main program
  511. that this mailbox matches the find request.  Note that the stream is
  512. locked and that therefore you cannot call any mail_xxx functions!
  513.  
  514. void mm_bboard (char *string)
  515.  This function is called from mail_find_bboards to notify the main
  516. program that this bboard matches the find request.  Note that the
  517. stream is locked and that therefore you cannot call any mail_xxx
  518. functions!
  519.  
  520. void mm_notify (MAILSTREAM *stream,char *string,long errflg)
  521.  This function is called when an unsolicited response of type OK, NO,
  522. or BAD from a remote IMAP server is received.  No newline is included
  523. in the string, so this function has to output its own.  The IMAP
  524. protocol defines this facility as a means for the server to transmit
  525. text for the end user to see.  Although the behavior of all possible
  526. IMAP server implementations can not be predicted, the following
  527. general assumptions can be made about the value of errflg and how it
  528. relates to the text based on how the C-client based IMAP server
  529. behaves:
  530.  NIL    normal operation.  The text is `babble' that the server
  531.     thinks may be interesting to the user.  Examples: the
  532.     greeting message from the server, notice of enabling of the
  533.     kludge to support MacMS, error in parsing the header of a
  534.     message in the remote mailbox (a C-client PARSE mm_log()
  535.     event).  Display of these messages to the user is optional.
  536.  WARN    A C-client WARN mm_log() event which occurred in the server.
  537.     See mm_log() documentation below.  This is also called from
  538.     the Berkeley mail driver if the requested mailbox write
  539.     operation failed because the main program returned NIL from
  540.     a "non-serious" mm_diskerror() call.
  541.  ERROR    An unknown IMAP protocol error, or an extremely serious
  542.     internal error.  These are supposedly impossible in debugged
  543.     software, and so should be called to the attention of the user
  544.     and/or support staff.  Whatever happened has probably already
  545.     disrupted the user's work, so it is alright to deal with this
  546.     in a modal fashion.
  547. Note that usually the stream is locked and that therefore you cannot
  548. call any mail_xxx functions!
  549.  
  550. void mm_log (char *string,long errflg)
  551.  This function is called on various C-client events.  No newline is
  552. included in the string, so this function has to output its own.  In
  553. general, it is intended that these be messages for the user to see.
  554. The value of errflg indicates the urgency of these messages, as
  555. follows:
  556.  NIL    normal operation.  The text is `babble' that the C-client
  557.     thinks may be interesting to the user.  Typically, these are
  558.     acknowledgement texts from various operations ("Expunged 3
  559.     messages", "Re-using connection", "Connection closing") which
  560.     may contain useful information.  Display of these messages to
  561.     the user is optional depending upon the needs of the
  562.     application.
  563.  PARSE    an error occurred in RFC 822 parsing.  Since bogus headers are
  564.     an all-too-common occurrence in the real word, these can often
  565.     be ignored on the GIGO principle.  However, it may be a good
  566.     idea to report these errors if calling the rfc822 routines as
  567.     part of command parsing e.g. mtp_parse_address().
  568.  WARN    an error condition occurred that did not abort the requested
  569.     operation, or which has a well-defined "right thing to do"
  570.     when it happens.  This can be things such as "Can't open
  571.     mailbox for read-write, so opening read-only", "Empty
  572.     mailbox", "Login failed, try again", "Waiting for mailbox to
  573.     become unlocked", etc.  Warnings can also occur if the abort
  574.     option is taken from mm_diskerror() to verify that the abort
  575.     has taken place.  Furthermore, it can occur (in massive
  576.     quantities!) in the event of a C-client detected IMAP
  577.     protocol error; but this should never happen in debugged
  578.     software.  Warnings should be called to the user's attention,
  579.     but probably should not interrupt the flow of the user's work
  580.     (that is, it's alright to display warnings in a view area
  581.     without waiting for any user acknowledgement of seeing the
  582.     warning).  It is not, however, absolutely necessary for an
  583.     application to display warnings.
  584.  ERROR    a serious error condition occured that aborted the requested
  585.     operation and possibly also aborted the mail stream.  This
  586.     ranges from normal error conditions such as "Can't open
  587.     mailbox", "too many login failures, go away" to bizarre
  588.     conditions such as "Apparent new mail appeared in the mailbox
  589.     that doesn't look like mail, program aborting".  Errors must
  590.     be called to the user's attention, and probably should require
  591.     some sort of acknowledgement (e.g. answering a modal panel)
  592.     before the application proceeds.
  593. Note that usually the stream is locked and that therefore you cannot
  594. call any mail_xxx functions!
  595.  
  596. void mm_dlog (char *string)
  597.  This function is called from several functions to output a string to
  598. a debugging telemetry stream.  No newline is included in the string,
  599. so this function has to output its own.  This is called only when
  600. debugging is enabled on the stream in question.  Note that usually the
  601. stream is locked and that therefore you cannot call any mail_xxx
  602. functions!
  603.  
  604. void mm_login (char *host,char *user,char *pwd,long trial)
  605.  This function is called to get a user name and password for the given
  606. host.  The function stores the user name and password in the strings
  607. pointed to by the appropriate arguments.  The trial argument is the
  608. number of attempts to perform the login and is initially zero (e.g.
  609. for a default username and password login functionality).  It is
  610. incremented for each subsequent trial until the maximum number of
  611. trials are made.  Note that the stream is locked and that therefore
  612. you cannot call any mail_xxx functions!
  613.  
  614. void mm_critical (MAILSTREAM *stream)
  615.  This function is called to alert the application that the C-client is
  616. about to run some critical code that may result in a clobbered mail
  617. file if it is interrupted.  Note that the stream is locked and that
  618. therefore you cannot call any mail_xxx functions!
  619.  
  620. void mm_nocritical (MAILSTREAM *stream)
  621.  This function is called to alert the application that the C-client is
  622. no longer running critical code that may result in a clobbered mail
  623. file if it is interrupted.  Note that the stream is locked and that
  624. therefore you cannot call any mail_xxx functions!
  625.  
  626. long mm_diskerror (MAILSTREAM *stream,long errcode,long serious)
  627.  This function is called to alert the application that the C-client
  628. has encountered an unrecoverable write error when trying to update the
  629. mail file.  errcode contains the system error code.  If serious is
  630. non-zero, then it is probable that the disk copy of the mailbox has
  631. been damaged.  The return value from this function is the abort flag;
  632. if serious is zero and the abort flag is non-zero, the operation is
  633. aborted.  If the abort flag is zero or if serious was non-zero, a
  634. return from this function will retry the failing operation.
  635.  
  636. void mm_fatal (char *string)
  637.  This function is called from the fatal() routine in the operating
  638. system code to notify the main program that it is about to crash.  The
  639. string contains a reason.  At the very minimum, the main program
  640. should do something like
  641.  mm_log (string,ERROR);
  642. and then return.  No newline is included in the string, so this
  643. function has to output its own.
  644.  
  645.             * * * IMPORTANT * * *
  646.  
  647.   Any multi-tasking application should test stream->lock prior to
  648. calling any functions in this module.  Any attempt to do a mail_*
  649. operation while one is already in progress on the same stream will
  650. cause the application to fail in unpredictable ways, mostly likely due
  651. to the _exit() calls in the internal mail_lock() routine when it
  652. discovers the stream is already locked.
  653.  
  654.  Note that this check is insufficient in a preemptive-scheduling
  655. multi-tasking application due to the possibility of a timing race.
  656. Such applications must be written so that only one process accesses
  657. the stream, or to have a higher level lock.
  658.  
  659.  Since MAIL operations will not finish until they are completed, a
  660. single-tasking application does not have to worry about this problem,
  661. except in the co-routines invoked from MAIL (e.g. mm_exists(), etc.)
  662. in which case the stream is *always* locked.
  663.  
  664.  
  665.        III. Operating system-dependent public interface
  666.  
  667.      The files listed below must be rewritten for each port of the
  668. C-client to a new operating system.
  669.  
  670. [OSDEP.C]:    operating system-dependent functions
  671.  
  672. #include "mail.h"
  673. #include "osdep.h"
  674.  
  675. void rfc822_date (char *date)
  676.  This function is called to get the current date and time in an RFC 822
  677. format string into the string pointed to by the argument.
  678.  
  679. void *fs_get (size_t size)
  680.  This function allocates and returns a block of free storage of the
  681. specified size.  Unlike malloc(), there is no failure return; this
  682. function must return with the requested storage.
  683.  
  684. void fs_resize (void **block,size_t size)
  685.  This function resizes the free storage block, updating the pointer if
  686. necessary.  Unlike realloc(), there is no failure return; this
  687. function must return with the requested storage.
  688.  
  689. void fs_give (void **block)
  690.  This function releases a block of free storage allocated by fs_get()
  691. and zeros the block pointer.
  692.  
  693. void fatal (char *string)
  694.  This function is called when an "impossible" error is detected and the
  695. client wishes to crash.  The string argument contains a reason string.
  696.  
  697. char *strcrlfcpy (char **dst,long *dstl,char *src,long srcl)
  698.  This function is called to copy into a destination string dst of size
  699. dstl (resized if necessary), a CRLF newline form string from local
  700. format string src of size srcl.
  701.  
  702. TCPSTREAM *tcp_open (char *host,long port)
  703.  This function is called to open a TCP connection to the given host
  704. name on the given port number.  It returns a TCPSTREAM, which is an
  705. internal data structure for this file and is implementation-dependent.
  706. NIL is returned if this function fails for any reason.
  707.  
  708. TCPSTREAM *tcp_aopen (char *host,char *service)
  709.  This function is called to open a connection to the given host name
  710. with the given service name.  At the present time, that service name
  711. is a Unix-format pathname (/etc/rimapd).  This function is expected to
  712. return a TCPSTREAM only if the connection was open and the user has
  713. been authenticated through an external mechanism such as the Unix r??
  714. protocols.
  715.  
  716. char *tcp_getline (TCPSTREAM *stream)
  717.  This function returns an fs_get() string containing a null-terminated
  718. text line from the TCP stream.  The CR/LF which terminated the line is
  719. not included.  The caller should free() the string when it is finished
  720. with it.  NIL is returned if this function fails for any reason.
  721.  
  722. long tcp_getbuffer (TCPSTREAM *stream,long size,char *buffer)
  723.  This function reads the requested number of bytes into the indicated
  724. buffer.  This function returns T if successful and NIL if it fails for
  725. any reason.
  726.  
  727. long tcp_soutr (TCPSTREAM *stream,char *string)
  728.  This function writes the indicated (null-terminated) string to the
  729. TCP stream.  This function returns T if successful and NIL if it fails
  730. for any reason.
  731.  
  732. void tcp_close (TCPSTREAM *stream)
  733.  The function closes the TCP stream and frees all resources associated
  734. with it that it may have created.
  735.  
  736. char *tcp_host (TCPSTREAM *stream)
  737.  This function returns the stream's foreign host name string.
  738.  
  739. char *tcp_localhost (TCPSTREAM *stream)
  740.  This function returns the stream's local host name string.
  741.  
  742.              IV. Driver interface
  743.  
  744.      When writing a new driver for the C-client, you must provide a
  745. DRIVER stucture giving a dispatch vector between MAIL and the driver.
  746. The DRIVER dispatch vector is described in MAIL.H.
  747.  
  748. [driver.C]:    driver for a particular mailbox type
  749.  
  750. #include "mail.h"
  751. #include "driver.h"
  752. #include "misc.h"
  753. #include "osdep.h"
  754.  
  755. DRIVER *next;
  756.  The first entry is a DRIVER * pointer to the next driver which this
  757. application supports (or NIL if this is the last driver).  Drivers are
  758. lunk together via the mail_link() function.  The remaining entries are
  759. function pointers as follows
  760.  
  761. DRIVER *driver_valid (char *name)
  762.  This function returns a pointer to the driver's DRIVER dispatch
  763. vector iff this driver accepts the given name as a valid mailbox for
  764. this driver.  Otherwise, it returns the value of the next driver's
  765. driver_valid() or NIL if there is no next driver.  In other words,
  766. calling driver_valid() for the first driver will return the driver
  767. dispatch vector for the driver which supports this type of mailbox.
  768.  
  769. void driver_find (MAILSTREAM *stream,char *pat)
  770.  This function implements mail_find() function for this driver.
  771.  
  772. void driver_find_bboard (MAILSTREAM *stream,char *pat);
  773.  This function implements mail_find_bboard() function for this driver.
  774.  
  775. MAILSTREAM *driver_open (MAILSTREAM *stream)
  776.  This function opens the mailbox identified by the given stream.  It
  777. may use the data on the stream and create additional data on
  778. stream->local as necessary.  It should return the given stream unless
  779. it failed to open the mailbox, in which case it should return NIL.
  780.  
  781. void driver_close (MAILSTREAM *stream)
  782.  This function implements mail_close() function for this driver.
  783.  
  784. void driver_fetchfast (MAILSTREAM *stream,char *sequence)
  785.  This function implements mail_fetchfast() function for this driver.
  786.  
  787. void driver_fetchflags (MAILSTREAM *stream,char *sequence)
  788.  This function implements mail_fetchflags() function for this driver.
  789.  
  790. ENVELOPE *driver_fetchstructure (MAILSTREAM *stream,long msgno,BODY **body)
  791.  This function implements mail_fetchstructure() function for this
  792. driver.
  793.  
  794. char *driver_fetchheader (MAILSTREAM *stream,long msgno)
  795.  This function implements mail_fetchheader() function for this driver.
  796.  
  797. char *driver_fetchtext (MAILSTREAM *stream,long msgno)
  798.  This function implements mail_fetchtext() function for this driver.
  799.  
  800. char *driver_fetchbody (MAILSTREAM *stream,long msgno,char *section)
  801.  This function implements mail_fetchbody() function for this driver.
  802.  
  803. void driver_setflag (MAILSTREAM *stream,char *sequence,char *flag)
  804.  This function implements mail_setflag() function for this driver.
  805.  
  806. void driver_clearflag (MAILSTREAM *stream,char *sequence,char *flag)
  807.  This function implements mail_clearflag() function for this driver.
  808.  
  809. void driver_search (MAILSTREAM *stream,char *criteria)
  810.  This function implements mail_search() function for this driver.
  811.  
  812. long driver_ping (MAILSTREAM *stream)
  813.  This function implements mail_ping() function for this driver.
  814.  
  815. void driver_check (MAILSTREAM *stream)
  816.  This function implements mail_check() function for this driver.
  817.  
  818. void driver_expunge (MAILSTREAM *stream)
  819.  This function implements mail_expunge() function for this driver.
  820.  
  821. long driver_copy (MAILSTREAM *stream,char *sequence,char *mailbox)
  822.  This function implements mail_copy() function for this driver.
  823.  
  824. long driver_move (MAILSTREAM *stream,char *sequence,char *mailbox)
  825.  This function implements mail_move() function for this driver.
  826.  
  827.      Drivers may call all of the MAIL functions documented above plus
  828. the following co-routine support functions:
  829.  
  830. void mail_searched (MAILSTREAM *stream,long msgno)
  831.  This function is called by the driver to notify MAIL that this
  832. message number matches a search.  It invokes the main program's
  833. mm_searched() function.
  834.  
  835. void mail_exists (MAILSTREAM *stream,long nmsgs)
  836.  This function is called by the driver to notify MAIL that this
  837. message number exists (i.e. there are this many messages in the
  838. mailbox).  It invokes the main program's mm_exists() function.
  839.  
  840. void mail_recent (MAILSTREAM *stream,long recent)
  841.  This function is called by the driver to notify MAIL that this
  842. many messages are "recent" (i.e. arrived in the mailbox since the
  843. previous time the mailbox was opened).
  844.  
  845. void mail_expunged (MAILSTREAM *stream,long msgno)
  846.  This function is called by the driver to notify MAIL that this
  847. message number has been expunged from the mail file and that all
  848. subsequent messages are no references by a message number one less
  849. than before.  It invokes the main program's mm_expunged() function.
  850.  
  851. void mail_lock (MAILSTREAM *stream)
  852.  This function sets the stream lock.  It is an error to set the stream
  853. lock if the stream is already locked.
  854.  This is mainly used to catch errors due to a co-routine function
  855. (e.g. mm_exists) inadvertantly recursing back to the MAIL routines and
  856. establishing an infinite recursion.  Normally, drivers will set the
  857. lock prior to calling one of the co-routine functions above or, more
  858. likely, in the beginning of the driver's non-reentrant "do operation"
  859. section.  In the IMAP2 driver, the stream lock is set when entering
  860. imap_send() and cleared on exit.
  861.  
  862. void mail_unlock (MAILSTREAM *stream)
  863.  This function releases the stream lock.  It is an error to release
  864. the stream lock if the stream is not locked.
  865.