| blob | 203688e815143a00b0ba001017b0073240f7fdbd |
1 /* ========================================================================
2 * Copyright 1988-2006 University of Washington
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 *
11 * ========================================================================
12 */
14 Documentation of c-client Functions and Interfaces
16 REVISED: 19 August 1996
18 Credits
20 The original version of this document was written by Mark Crispin at
21 the University of Washington, and described the version of c-client that
22 supported the IMAP2 (RFC 1176) and IMAP2bis (unpublished) protocols.
24 This version is a substantial rewrite of that document, and was
25 written by Mark Crispin with funding from Sun Microsystems, Incorporated.
26 Sun's generous support of this work is gratefully acknowledged.
29 Road Map
31 This document is organized into the following sections. Except as
32 noted, an implementor of an application that uses c-client needs to be
33 familiar with all of these sections. Someone who plans to write a new
34 mailbox driver for c-client (or otherwise modify it) needs to be familiar
35 with all sections, no exception.
37 History
38 History of how c-client came about.
40 Overview
41 Read this before designing an application that uses c-client.
43 c-client Structures
44 Documentation of several important c-client structs which are
45 used in, and returned by, c-client calls.
47 String Structures
48 Documentation of the concept of a "string structure", which
49 provides random access to strings without requiring that the
50 string be in memory.
52 c-client Support Functions
53 Documentation of support functions for c-client; these deal
54 with c-client functionality.
56 Only mail_parameters() is of interest to most application
57 developers. Advanced application developers, particularly
58 for limited memory systems, may also need to know about the
59 readfn_t, mailgets_t, mailcache_t, and tcptimeout_t function
60 pointer types, and possibly also the mail_valid_net_parse()
61 function.
63 Mailbox Access Functions
64 Documentation of functions which deal with mailboxes;
65 listing, subscribing, creating, deleting, renaming, status
66 inquiries, opening, and closing mailboxes.
68 Handle Functions
69 Documentation of mail stream handles, which provide protection
70 for an advanced application which may have multiple pointers to
71 a single mail stream. If a stream has a handle on it, closing
72 the stream does not release its memory, so pointers to it in
73 the application remain valid. Freeing the last handle will free
74 the entire stream.
76 This is only of interest for advanced application developers.
78 Message Data Fetching Functions
79 Documentation on message data fetching in an open mailbox,
80 including parsed representations of RFC-822 and MIME headers
81 and message text. Also how to fetch message attributes (flags,
82 internal date, sizes).
84 Message Status Manipulation Functions
85 Documentation on altering message flags in an open mailbox.
87 Mailbox Searching
88 Documentation on searching an open mailbox for messages which
89 match certain criteria (e.g. "messages sent July 4 from Jones
90 with text `Paris'").
92 Miscellaneous Mailbox and Message Functions
93 Documentation on other operations that would be used by an
94 application but that don't fit into any of the above categories.
96 Date/Time Handling Functions
97 Documentation on functions that deal with date/time strings.
99 This is only of interest for advanced application developers
100 and for implementors of new c-client drivers.
102 Utility Functions
103 Documentation on internal utility functions.
105 This is primarily of interest for implementors of new c-client
106 drivers, but advanced application developers may also use some
107 of these functions.
109 Data Structure Instantiation/Destruction functions
110 Documentation on creating and destroy c-client structures.
112 This is primarily of interest for implementors of new c-client
113 drivers. However, application developers will need some of
114 these functions to create and destroy structures which are used
115 as arguments to various application functions.
117 Authentication Functions
118 Documentation on support for network protocol authentication
119 functions.
121 This is only of interest for implementors of new c-client
122 drivers which deal with authentication mechanisms.
124 Network Access Functions
125 Documentation on creating and destroy c-client structures.
127 This is primarily of interest for implementors of new c-client
128 drivers which deal with a network. However, advanced
129 application developers may need to use this information if they
130 wish to insert their own layer into a network session.
132 Subscription Management Functions
133 Documentation on managing the local (client-based) subscription
134 database file.
136 This is primarily of interest to advanced application developers.
138 Miscellaneous Utility Functions
139 Documentation on various useful utility functions, such as "make
140 a copy of this string."
142 SMTP Functions
143 Documentation on posting email messages via SMTP protocol.
145 NNTP Functions
146 Documentation on posting netnews messages via NNTP protocol.
148 RFC 822 Support Functions
149 Documentation on public RFC-822/MIME functions.
151 This is primarily of interest for implementors of new c-client
152 drivers and advanced application developers.
154 Operating System-Dependent Public Interface
155 Documentation on OS-dependent functions. With the exception of
156 fs_get(), fs_give(), and fs_resize(), which should be called
157 instead of malloc(), free(), and realloc(), these functions are
158 primarily of interest for implementors of new c-client drivers.
160 Main Program Callbacks
161 Documentation of functions which the main program must provide
162 as callbacks from c-client.
164 Driver Interface
165 Documentation of the driver dispatch vector and the functions
166 which a driver must supply.
168 This is primarily of interest for implementors of new c-client
169 drivers.
171 Driver Support Functions
172 Documentation of support functions which are called by drivers.
174 This is primarily of interest for implementors of new c-client
175 drivers.
176 \f History
178 The c-client API was originally written by Mark Crispin at Stanford
179 University as a set of routines to support IMAP and SMTP from a main
180 program which would handle the user interface. In its original form, it
181 was written as the low-level routines that were to be used as part of a
182 Macintosh client.
184 The first IMAP client, MM-D (for "MM on Xerox D machines" -- MM was a
185 popular DEC-20 mail program) was written in Interlisp for Xerox Lisp
186 machines. At that time, there was no name for the embryonic Mac client,
187 but since it was the first one to be written in C instead of Lisp, it was
188 given a development name of "C client". This name became "c-client"
189 because that is the name of the subdirectory on UNIX where the source files
190 were stored.
192 To exercise the routines, a minimal main program which uses c-client,
193 mtest, was written. mtest has subsequently been extended so that it runs
194 on every platform that c-client is ported.
196 The real Mac client, was eventually written by Frank Gilmurrary and
197 Bill Yeager at Stanford using the autumn 1988 version of c-client and named
198 "MacMS". In the winter of 1988-89, Mark Crispin, who had changed jobs to
199 the University of Washington, developed MS as an MM-like text-based program
200 for UNIX and MailManager as a GUI-based program for NeXT machines.
202 The realization sunk in that this API needed its own name. As early
203 as spring 1989, there were at least four programs (mtest, MS, MailManager,
204 and MacMS) that used it. The name c-client thus became permanent.
206 In its history, c-client has undergone two major redesigns, both by
207 Mark Crispin who is now on the staff at the University of Washington.
209 The first major redesign added the following:
210 1) ANSI C calling conventions throughout to assist in function
211 argument type checking.
212 2) Vectoring mail access calls through "driver" methods; thus
213 providing transparent access to multiple types of mail
214 stores with the same call.
215 3) MIME support.
217 The second major redesign was part of the IMAP4 project. Many
218 c-client functions were extended with additional arguments and options.
219 The driver interface was also made simpler, with more work done by
220 driver-independent code.
221 \f
222 Overview
224 The most important file for the author of an application using the
225 c-client is mail.h. mail.h defines several important structures of
226 data which are passed between the main program and the c-client.
227 Although some functions (e.g. mail_fetchtext_body()) return the data
228 fetched, for certain other data items (e.g. flags) you need to get the
229 data as a structure reference. mail.h also defines a large number of
230 useful constants and structures.
232 When a function in mail.h exists to reference data, it MUST be
233 used instead of referencing the structures directly. This is because
234 in some cases the data is not actually fetched until a reference (via
235 the function call) is made. For example, although the MESSAGECACHE
236 element for a message can be obtained by indexing the proper cache
237 element in the stream, there is no guarantee that the item in fact
238 exists unless mail_fetchstructure_full() is called for that message.
239 Less costly functions. also exist to create and load a MESSAGECACHE
240 element.
242 The main program will probably also need to include smtp.h,
243 misc.h, and osdep.h, but this usage should be solely to receive
244 function prototypes. Any other definitions in those files should be
245 considered private to that module.
247 Two important predefined symbols are NIL and T. NIL is any sort
248 of "false"; T is any sort of "true". NIL is also used to null-specify
249 certain optional arguments.
251 * * * IMPORTANT * * *
253 Any multi-threaded application should test stream->lock prior to
254 calling any c-client stream functions. Any attempt to call a
255 mail_xxx() function while one is already in progress on the same
256 stream will cause the application to fail in unpredictable ways.
258 Note that this check is insufficient in a preemptive-scheduling
259 multi-tasking application due to the possibility of a timing race.
260 Such applications must be written so that only one process accesses
261 the stream, or to have a higher level lock.
263 Since MAIL operations will not finish until they are completed, a
264 single-tasking application does not have to worry about this problem,
265 except in the callback invoked from MAIL (e.g. mm_exists(), etc.) in which
266 case the stream is *always* locked.
267 \f
268 c-client Structures
270 c-client has a large number of structures which are used for
271 multiple functions. The most important of these are described here.
273 The MAILSTREAM structure is used to reference open mailboxes.
274 Applications may reference the following:
276 char *mailbox; mailbox name
277 unsigned short use; stream use count, this is incremented
278 unsigned short sequence; stream sequence, this is incremented
279 each time a stream is reused (i.e.
280 mail_open() is called to open a
281 different mailbox on this stream)
282 unsigned int rdonly : 1; stream is open read-only
283 unsigned int anonymous : 1; stream is open with anonymous access
284 unsigned int halfopen : 1; stream is half-open; it can be
285 reopened or used for functions that
286 don't need a open mailbox such as
287 mail_create() but no message data
288 can be fetched
289 unsigned int perm_seen : 1; Seen flag can be set permanently
290 unsigned int perm_deleted : 1; Deleted flag can be set permanently
291 unsigned int perm_flagged : 1; Flagged flag can be set permanently
292 unsigned int perm_answered :1; Answered flag can be set permanently
293 unsigned int perm_draft : 1; Draft flag can be set permanently
294 unsigned int kwd_create : 1; new user flags can be created by
295 referencing then in mail_setflag() or
296 mail_clearflag(). Note: this can
297 change during a session (e.g. if
298 there is a limit on the number of
299 keywords), so check after creating a
300 new flag to see if any more can be
301 created before letting the user try
302 to do so
303 unsigned long perm_user_flags; corresponding user flags can be set
304 permanently. This is a bit mask
305 which matches the entries in
306 stream->user_flags[]
307 unsigned long gensym; generated unique value. Always
308 referenced with stream->gensys++
309 unsigned long nmsgs; number of messages in current mailbox
310 unsigned long recent; number of recent messages in current
311 mailbox
312 unsigned long uid_validity; UID validity value; this is used to
313 verify that recorded UIDs match the
314 UIDs that the stream has. If the
315 mailbox does not have matching UIDs
316 (e.g. the UIDs were lost or not
317 recorded) then the UID validity value
318 will be different
319 unsigned long uid_last; highest currently assigned UID in the
320 current mailbox; a new UID will be
321 assigned with ++stream->uid_last
322 char *user_flags[NUSERFLAGS]; pointers to user flag names in bit
323 order from stream->perm_user_flags or
324 elt->user_flags
326 The following MAILSTREAM values are only used internally:
328 DRIVER *dtb; dispatch table for this driver
329 void *local; pointer to driver local data
330 unsigned int lock : 1; stream lock flag (an operation is in
331 progress; used as a bug trap to
332 detect recursion back to c-client
333 from callback routines).
334 unsigned int debug : 1; debugging information should be logged
335 via mm_dlog().
336 unsigned int silent : 1; don't do main program callbacks on
337 this stream (used when a stream is
338 opened internally)
339 unsigned int scache : 1; short caching; don't cache information
340 in memory
342 The following MAILSTREAM values are only used by the cache
343 manager routine (see the documentation about mailcache_t above):
345 unsigned long cachesize; size of c-client message cache
346 union {
347 void **c; to get at the cache in general
348 MESSAGECACHE **s; message cache array
349 LONGCACHE **l; long cache array
350 } cache;
352 The following MAILSTREAM values are for the convenience of
353 drivers that use short caching and want to be able to garbage collect
354 any values that they returned:
356 unsigned long msgno; message number of `current' message
357 ENVELOPE *env; pointer to `current' message envelope
358 BODY *body; pointer to `current' message body
359 char *text; pointer to `current' text
362 The MESSAGECACHE structure (commonly called an "elt" as a
363 nickname for "cache ELemenT") contains information about messages.
364 Applications may use the following:
366 unsigned long msgno; message number. If the elt is locked
367 (by elt->lockcount++), then the elt
368 pointer can be stored (e.g. with the
369 data for a window which draws this
370 message) and elt->msgno will change
371 automatically whenever expunges are
372 done so the window will always view
373 the correct message. If elt->msgno
374 becomes 0, then the message has been
375 expunged, but the elt won't be freed
376 until the elt lock count is
377 decremented (by mail_free_elt()).
378 unsigned long uid; message unique ID
379 unsigned int hours: 5; internal date hours (0-23)
380 unsigned int minutes: 6; internal date minutes (0-59)
381 unsigned int seconds: 6; internal date seconds (0-59)
382 unsigned int zoccident : 1; non-zero if internal date time zone is
383 west of UTC
384 unsigned int zhours : 4; internal date time zone hours from UTC
385 (0-12)
386 unsigned int zminutes: 6; internal date time zone minutes (0-59)
387 unsigned int seen : 1; message Seen flag
388 unsigned int deleted : 1; message Deleted flag
389 unsigned int flagged : 1; message Flagged flag
390 unsigned int answered : 1; message Answered glag
391 unsigned int draft : 1; message Draft flag
392 unsigned int valid : 1; flags are valid in this elt; an elt
393 that was newly created but never
394 loaded with flags won't have this set.
395 unsigned int recent : 1; message recent flag
396 unsigned int searched : 1; message matches search criteria in
397 most recent mail_search_full() call
398 unsigned int spare : 1; reserved for application use
399 unsigned int spare2 : 1; reserved for application use
400 unsigned int spare3 : 1; reserved for application use
401 unsigned int lockcount : 8; non-zero if multiple references to
402 this elt. Refer to the msgno member
403 for more information.
404 unsigned int day : 5; internal date day of month (1-31)
405 unsigned int month : 4; internal date month of year (1-12)
406 unsigned int year : 7; internal date year since BASEYEAR
407 (currently 1970; was 1969 in older
408 versions so use BASEYEAR instead of
409 having the base year wired in)
410 unsigned long user_flags; message user flags; this is a bit mask
411 which matches the entries in
412 stream->user_flags[]
413 unsigned long rfc822_size; size of message in octets
415 The following MESSAGECACHE values are only used internally by
416 drivers:
418 unsigned int sequence : 1; message is in sequence from either
419 mail_sequence() or mail_uid_sequence()
420 unsigned long data1; first data item
421 unsigned long data2; second data item
422 unsigned long data3; third data item
423 unsigned long data4; fourth data item
426 The ADDRESS structure is a parsed form of a linked list of RFC 822
427 addresses. It contains the following information:
429 char *personal; personal name phrase
430 char *adl; at-domain-list (also called "source
431 route")
432 char *mailbox; mailbox name
433 char *host; domain name of mailbox's host
434 char *error; error in address from smtp_mail(); if
435 an error is returned from smtp_mail()
436 for one of the recipient addresses
437 the SMTP server's error text for that
438 recipient can be found here. If it
439 is null then there was no error (or
440 an error was found with a prior
441 recipient
442 ADDRESS *next; pointer to next address in list
445 The ENVELOPE structure is a parsed form of the RFC 822 header.
446 Its member names correspond to the RFC 822 field names. It contains
447 the following information:
449 char *remail; remail header if any
450 ADDRESS *return_path; error return address
451 char *date; message composition date string
452 ADDRESS *from; from address list
453 ADDRESS *sender; sender address list
454 ADDRESS *reply_to; reply address list
455 char *subject; message subject string
456 ADDRESS *to; primary recipient list
457 ADDRESS *cc; secondary recipient list
458 ADDRESS *bcc; blind secondary recipient list
459 char *in_reply_to; replied message ID
460 char *message_id; message ID
461 char *newsgroups; USENET newsgroups
462 char *followup_to; USENET reply newsgroups
463 char *references; USENET references
466 The BODY structure is a parsed form of a linked list of the MIME
467 structure of a message. It contains the following information.
469 unsigned short type; body primary type code. This is an
470 index into the body_types vector of
471 body type names. The following body
472 types are pre-defined:
473 TYPETEXT unformatted text
474 TYPEMULTIPART multiple part
475 TYPEMESSAGE encapsulated message
476 TYPEAPPLICATION application data
477 TYPEAUDIO audio
478 TYPEIMAGE static image (GIF, JPEG, etc.)
479 TYPEVIDEO video
480 TYPEOTHER unknown
481 Additional types up to TYPEMAX are
482 dynamically defined if they are
483 encountered by c-client.
484 unsigned short encoding; body transfer encoding. This is an
485 index into the body_encodings vector
486 of body encoding names. The
487 following body encodings are
488 pre-defined:
489 ENC7BIT 7 bit SMTP semantic data
490 ENC8BIT 8 bit SMTP semantic data
491 ENCBINARY 8 bit binary data
492 ENCBASE64 base-64 encoded data
493 ENCQUOTEDPRINTABLE human-readable 8-as-7 bit data
494 ENCOTHER unknown
495 Additional encodings up to ENCMAX are
496 dynamically defined if they are
497 encountered by c-client.
498 char *subtype; body subtype string
499 PARAMETER *parameter; parameter list
500 char *id; body content identifier
501 char *description; body content description
502 unsigned char *contents.text; when composing a message that is NOT
503 of TYPEMULTIPART, non-binary text of
504 the content is stored here. Note that
505 this happens even when the text is
506 of TYPEMESSAGE. Text of encoding
507 ENC8BIT may be converted to
508 ENCQUOTEDPRINTABLE when it is sent.
509 This should not be referenced for any
510 other reason; in particular, this is
511 NOT the way for an application to
512 access content data (use
513 mail_fetchbody_full() instead).
514 BINARY *contents.binary; when composing a message that is NOT
515 of TYPEMULTIPART, binary content (of
516 encoding ENCBINARY) is stored here.
517 It will be converted to ENCBASE64 when
518 it is sent.
519 This should not be referenced for any
520 other reason; in particular, this is
521 NOT the way for an application to
522 access content data (use
523 mail_fetchbody_full() instead).
524 PART *contents.part; for body parts of TYPEMULTIPART, this
525 contains the list of body parts in
526 this multipart
527 MESSAGE contents.msg; for body parts of TYPEMESSAGE with
528 subtype "RFC822", this contains the
529 encapsulated message
530 unsigned long size.lines; size in lines
531 unsigned long size.bytes; size in octets. This MUST be set when
532 composing a message if the encoding is
533 ENC8BIT or ENCBINARY.
534 char *md5; body content MD5 checksum
536 The following BODY information is used only by c-client
537 internally. The use of this data is driver-specific and it can not be
538 relied-upon by applications.
540 unsigned char *contents.text; drivers can store a pointer to the
541 body contents as text here.
542 unsigned long size.ibytes; internal size of the body content (prior
543 to newline conversion, etc.) in octets
546 The MESSAGE structure is a parsed form of a MESSAGE/RFC822 MIME
547 body part. It contains the following information:
549 ENVELOPE *env; encapsulated message RFC 822 header
550 BODY *body; encapsulated message MIME structure
552 The following MESSAGE information is used only by c-client
553 internally. The use of this data is driver-specific and it can not be
554 relied-upon by applications.
556 char *hdr; encapsulated message header
557 unsigned long hdrsize; message header size
558 char *text; message in RFC 822 form
559 unsigned long offset; offset of text from header
562 The PARAMETER structure is a parsed form of a linked list of
563 attribute/value pairs. It contains the following information:
565 char *attribute; attribute name
566 char *value; value
567 PARAMETER *next; next parameter in list
570 The PART structure is a parsed form of a linked list of MIME body
571 parts. It contains the following information:
573 BODY body; body information for this part
574 PART *next; next body part
576 The following PART information is used only by c-client
577 internally. The use of this data is driver-specific and it can not be
578 relied-upon by applications.
580 unsigned long offset; offset from body origin
583 The NETMBX structure is a parsed form of a network mailbox name:
585 char host[NETMAXHOST]; remote host name
586 char user[NETMAXUSER]; remote user name if specified
587 char mailbox[NETMAXMBX]; remote mailbox name
588 char service[NETMAXSRV]; remote service name (IMAP4, NNTP, etc.)
589 unsigned long port; TCP/IP port number if specified
590 unsigned int anoflag : 1; anonymous access requested
591 unsigned int dbgflag : 1; protocol debugging telemetry, via
592 mm_dlog(), requested
595 The STRINGLIST structure is a list of strings (which may have
596 embedded NULs) and their lengths:
598 char *text; string text
599 unsigned long size; string length
600 STRINGLIST *next; next string in list
601 \f
602 String Structures
604 A string structure is analogous to a char*, and is used in some
605 functions as an input argument. It represents a string of data in a
606 way that does not necessarily require the entire string to be in
607 memory at once. This is essential for small machines with
608 highly-restricted memory limits (e.g. DOS).
610 String Structure Access
612 To use a string structure, the caller needs to know a string
613 driver and needs to know the driver-dependent data used by that string
614 structure. A simple string driver is mail_string, a string driver
615 that takes an in-memory char* string as the driver-dependent data.
616 The DOS port uses string drivers that take a struct holding a file
617 descriptor and a file offset. Often the user of a string driver is
618 the same module that defined it, so usually the programmer knows about
619 its conventions.
621 The following calls are used to access a string structure:
623 void INIT (STRING *s,STRINGDRIVER *d,void *data,unsigned long size);
624 s pointer to the string structure to be initialized
625 d pointer to the string driver
626 data pointer to driver-dependent data, from which the
627 driver can determine string data
628 size size of the string
629 This call initializes the string stucture.
632 unsigned long SIZE (STRING *s);
633 s pointer to the string structure
634 This call returns the number of characters remaining in the string
635 after the current string character pointer.
638 char CHR (STRING *s);
639 s pointer to the string structure
640 This call returns the character at the current string character
641 pointer.
644 char SNX (STRING *s);
645 s pointer to the string structure
646 This call returns the character at the current string character
647 pointer, and increments the string character pointer.
650 unsigned long GETPOS (STRING *s);
651 s pointer to the string structure
652 This returns the value of the current string character pointer.
655 void SETPOS (STRING *s,unsigned long i);
656 s pointer to the string structure
657 i new string pointer value
658 This method sets the string character pointer to the given value.
661 String Structure Internals
663 A string structure holds the following data:
665 void *data; used by the string driver as it likes
666 unsigned long data1; used by the string driver as it likes
667 unsigned long size; static, holds the total length of the string
668 from the INIT call
669 char *chunk; current chunk of in-memory data; this is used
670 for buffering to avoid unnecessary calls to
671 the string driver's next method.
672 unsigned long chunksize; size of an in-memory data chunk
673 unsigned long offset; position of first character of the chunk in
674 the overall string
675 char *curpos; current position; this is what CHR() will
676 access
677 unsigned long cursize; number of characters remaining in the current
678 string
679 STRINGDRIVER *dtb; the string driver for this string structure
682 A string structure is manipulated by a string driver, which has
683 the following access methods:
685 void (*init) (STRING *s,void *data,unsigned long size);
686 s pointer to the string structure to be initialized
687 data pointer to driver-dependent data, from which the
688 driver can determine string data
689 size size of the string
690 This method initializes the string stucture. It can use the data,
691 data1, and chunksize values as it likes. The remaining values must be
692 set up as follows:
693 size static, copied from the size argument
694 chunk pointer to a buffer loaded with initial data
695 chunksize size of the buffer
696 offset 0
697 curpos copied from chunk
698 cursize copied from chunksize
699 dtb STRINGDRIVER identity pointer
702 char (*next) (STRING *s);
703 s pointer to the string structure
704 This method returns the character at the current string character
705 pointer, and increments the string character pointer. This method
706 is likely to call the setpos method if the desired character is not in
707 the current chunk.
710 void (*setpos) (STRING *s,unsigned long i);
711 s pointer to the string structure
712 i new string pointer value
713 This method sets the string character pointer to the given value. If
714 the pointer is not in the current chunk, then a new chunk is loaded
715 and the associated values (chunk, offset, curpos, cursize) are
716 adjusted accordingly.
717 \f
718 c-client Support Functions
721 void mail_string_init (STRING *s,void *data,unsigned long size);
722 char mail_string_next (STRING *s);
723 void mail_string_setpos (STRING *s,unsigned long i);
725 These three functions are the init, next, and setpos string
726 structure access methods for the build-in mail_string string driver.
727 mail_string is a basic string driver for a char* string. See the
728 documentation below on "String Structures" for more information.
731 void mail_link (DRIVER *driver);
732 driver pointer to the driver to be added
734 This function adds the specified driver to the list of mailbox
735 drivers. Initially there are no drivers lunk, so all programs which
736 intend to use c-client need to have at least one call to this function.
738 A function which uses IMAP4 would have a statement such as:
739 mail_link (&imapdriver); /* link in IMAP driver */
740 early in the program's initialization. Normally, this is done by the
741 statement
742 #include "linkage.c"
743 which will include the "system standard driver linkage" defined when
744 c-client was built. By using linkage.c instead of explicit mail_link()
745 calls, you are guaranteed that you will have a consistant linkage among
746 all software built on this system.
749 void auth_link (AUTHENTICATOR *auth);
750 auth pointer to the authenticator to be added
752 This function adds the specified authenticator to the list of
753 authenticators. Initially there are no authenticators lunk. Normally,
754 this is done by linkage.c so you don't need to call this routine
755 explicitly.
758 void *mail_parameters (MAILSTREAM *stream,long function,void *value);
759 stream stream to poll or NIL
760 function function code
761 value new value for function codes that change a parameter
763 This function fetches or changes the settings of various c-client
764 operational parameters depending upon the function. If the stream is
765 specified, only the action for the underlying driver for that stream is
766 taken; however, the scope of the operational parameters is global so
767 there is generally no reason for the stream argument ever to be
768 non-NIL.
770 The function codes ENABLE_DRIVER and DISABLE_DRIVER take a driver
771 pointer as a value. These functions enable and disable mailbox
772 processing by that driver. By default, all drivers are enabled.
774 The remaining function codes are in a pair named GET_xxx to
775 fetch an operational parameter and SET_xxx to set the parameter:
777 GET_DRIVERS / SET_DRIVERS
778 The list of currently lunk drivers.
780 GET_GETS / SET_GETS
781 If non-NIL, points to a function for reading message text.
782 Defaults to NIL.
783 This function is called with three arguments; a function
784 pointer to a "reading function", a stream for the reading
785 function, and a size in octets. The reading function is
786 in turn called with the stream, a size in octets, and a
787 pointer to a readin buffer.
788 This function returns with a char* string, which will be
789 returned by the mail_fetchheader(), mail_fetchtext(), or
790 mail_fetchbody() function which triggered the message text
791 reading.
792 The purpose is to permit reading of large strings, without
793 requiring an in-memory buffer for the entire string. The idea
794 is that this function can store the data in some form other
795 than a char* (e.g. a temporary file) and the main program will
796 recognize that it should get the text from there instead of
797 from the results from mail_fetch....().
798 This is only supported on DOS and Win16; on other platforms it
799 is inconsistent whether or not it works.
801 GET_CACHE / SET_CACHE
802 Points to the c-client cache manager function. Defaults to
803 mm_cache().
805 GET_SMTPVERBOSE / SET_SMTPVERBOSE
806 If non-NIL, points to a function that accepts a char* string.
807 This function is called any time the SMTP routines receive a
808 response code less than 100. The argument is the text of the
809 response code
811 GET_RFC822OUTPUT / SET_RFC822OUTPUT
812 If non-NIL, points to an alternate rfc822_output() function.
813 rfc822_output() will call this function and return instead of
814 doing its normal action. See the description of
815 rfc822_output() for more information.
817 GET_USERNAME / SET_USERNAME
818 The logged-in user name.
820 GET_HOMEDIR / SET_HOMEDIR
821 The home directory path name.
823 GET_LOCALHOST / SET_LOCALHOST
824 The local host name.
826 GET_SYSINBOX / SET_SYSINBOX
827 The "system INBOX" (where mail is delivered) path name.
829 GET_OPENTIMEOUT / SET_OPENTIMEOUT
830 TCP/IP open timeout in seconds. Defaults to 0 (system
831 default timeout, usually 75 seconds on Unix).
833 GET_READTIMEOUT / SET_READTIMEOUT
834 TCP/IP read timeout in seconds. Defaults to 0 (no timeout).
836 GET_WRITETIMEOUT / SET_WRITETIMEOUT
837 TCP/IP write timeout in seconds. Defaults to 0 (no timeout).
839 GET_CLOSETIMEOUT / SET_CLOSETIMEOUT
840 TCP/IP close timeout in seconds. Defaults to 0 (no timeout).
842 GET_TIMEOUT / SET_TIMEOUT
843 If non-NIL, points to the function called when a TCP/IP
844 timeout occurs. This function is called with the number of
845 seconds since the start of the TCP operation. If it returns
846 non-zero, the TCP/IP operation is continued; if it returns
847 non-zero, the TCP/IP connection is aborted.
849 GET_RSHTIMEOUT / SET_RSHTIMEOUT
850 rsh connection timeout in seconds. Defaults to 15 seconds.
852 GET_MAXLOGINTRIALS / SET_MAXLOGINTRIALS
853 The maximum number of login attempts permitted in an IMAP or
854 POP connection. Defaults to 3.
856 GET_LOOKAHEAD / SET_LOOKAHEAD
857 The number of subsequent envelopes prefetched in IMAP when an
858 envelope is fetched. Defaults to 20.
860 GET_IMAPPORT / SET_IMAPPORT
861 The IMAP port number. Defaults to 143.
863 GET_PREFETCH / SET_PREFETCH
864 The number of envelopes prefetched in IMAP from the results
865 of a SEARCH. Defaults to 20.
867 GET_CLOSEONERROR / SET_CLOSEONERROR
868 If non-NIL, close an opening IMAP connection if the SELECT
869 command fails instead of returning a half-open stream.
870 Defaults to NIL.
872 GET_POP3PORT / SET_POP3PORT
873 The POP3 port number. Defaults to 110.
875 GET_UIDLOOKAHEAD / SET_UIDLOOKAHEAD
876 The number of UIDs premapped when a message number is
877 translated to a UID. Defaults to 1000.
879 GET_MBXPROTECTION / SET_MBXPROTECTION
880 Default file protection for newly created mailboxes.
881 Defaults to 0600.
883 GET_DIRPROTECTION / SET_DIRPROTECTION
884 Default file protection for newly created directories.
885 Defaults to 0700.
887 GET_LOCKPROTECTION / SET_LOCKPROTECTION
888 Default file protection for locks. Defaults to 0666.
889 WARNING: don't blithely change this. If other processes
890 can't get access to a lock then they will have trouble in
891 locking properly.
893 GET_FROMWIDGET / SET_FROMWIDGET
894 If non-NIL, APPEND in the Unix mbox format will insert a
895 ">" character in front of all lines which begin with the
896 string "From ". If NIL, it will only do so if the entire
897 line looks like a message delimiter (that is, the date is
898 also in correct format). Defaults to T.
900 GET_NEWSACTIVE / SET_NEWSACTIVE
901 Netnews active file path name.
903 GET_NEWSSPOOL / SET_NEWSSPOOL
904 Netnews spool directory path name.
906 GET_NEWSRC / SET_NEWSRC
907 Netnews newsgroup reading status file (.newsrc) path name.
909 GET_EXTENSION / SET_EXTENSION
910 If non-NIL, points to a string holding the extension for all
911 mailbox files. This is only supported on DOS and Win16.
913 GET_DISABLEFCNTLLOCK / SET_DISABLEFCNTLLOCK
914 If non-NIL, disables fcntl() locking on SVR4. This is done
915 if fcntl() tends to hang for no good reason. Now that the
916 fcntl() code checks for NFS files and no-ops the locking,
917 this problem usually doesn't happen much any more. Defaults
918 to NIL.
920 GET_LOCKEACCESERROR / SET_LOCKEACCESERROR
921 If non-NIL, give a warning if an attempt to create a .lock
922 file gets an EACCES ("Permission denied") error. This usually
923 means that somebody protected the system inbox directory (e.g.
924 /var/mail) instead of making it public-write with the sticky
925 bit. Defaults to non-NIL, since this is usually bad news.
927 GET_LISTMAXLEVEL / SET_LISTMAXLEVEL
928 The maximum depth of recusion that LIST will go on a *
929 wildcard. Defaults to 20.
931 GET_ANONYMOUSHOME / SET_ANONYMOUSHOME
932 The anonymous use home directory name.
935 typedef long (*readfn_t) (void *stream,unsigned long size,char *buffer);
936 stream a designator suitable
937 size a number of octets to read
938 buffer a buffer of at least size octets for readin
940 This function reads the given number of octets into the buffer,
941 using the given stream. What sort of object the stream is depends upon
942 the function and its caller, so you must make sure that the readfn is
943 suitable for the caller's purpose. Common uses include support of the
944 mailgets function (see below) and of reading from local files on systems
945 with limited address space.
948 typedef char *(*mailgets_t) (readfn_t f,void *stream,unsigned long size);
949 f the readfn to use
950 stream stream argument for the readfn
951 size total number of octets to read
953 This is the argument to the SET_GETS mail_parameter() call. This
954 function must read size octets from the stream, using the readfn f. It
955 may call f multiple times to accomplish this; this will read the data in
956 a serial fashion. So, for example, if size is a megabyte and there is
957 only 4K of available buffer space, it can call f 256 times to satisfy
958 the request. There is no way to back up in the reading, so any
959 processing or saving of the data must be done when it is read.
961 The function mm_gets() in mail.c is a sample mailgets function; it
962 reads the first MAXMESSAGESIZE of data into memory and discards the
963 rest.
966 typedef void *(*mailcache_t) (MAILSTREAM *stream,unsigned long msgno,long op);
967 stream stream to cache manage
968 msgno message to cache manage in the stream
969 op cache management operation
971 This function manages the c-client cache. Normally, a program will
972 use the default c-client cache manager routine mm_cache(). However, a
973 main program may want to supply its own cache manager, e.g. it may want
974 to store the data on a disk file instead of in memory on DOS and Win16
975 where memory is tight.
977 If you write your own cache manager, you need to examine the
978 default mm_cache() manager closely, as well as paying close attention to
979 what goes into an elt (a MESSAGECACHE element). It is highly likely
980 that if you roll elts out to disk, you will want to set stream->scache
981 and *NOT* use long elts (because long elts have ENVELOPE and BODY
982 pointers that you would have to know how to write to disk and read back).
984 The cache management functions are one of the following:
986 CH_INIT Initialize the entire cache for the stream. This is
987 called only when creating a new stream or when freeing
988 it. The msgno argument is ignored.
990 CH_SIZE Make sure that the cache is at least large enough to
991 support msgno. This is a request to grow the cache if
992 necessary, not shrink it.
994 CH_MAKELELT Return a long elt for msgno, creating it if necessary.
995 This is the underlying support function for mail_lelt().
997 CH_LELT Return the long elt for msgno, or NIL if it does not
998 already exist.
1000 CH_MAKEELT Return an elt for msgno, creating it if necessary.
1001 This is the underlying support function for mail_elt().
1003 CH_ELT Return the elt for msgno, or NIL if it does not already
1004 exist.
1006 CH_FREE Free the [l]elt for msgno.
1008 CH_EXPUNGE Free the [l]elt for msgno, and reclaim its position.
1009 All subsequent elts are renumbered with their elt->msgno
1010 decremented by 1. [Hence msgno+1 becomes msgno, etc.]
1011 This supports message expunging from the cache.
1014 typedef long (*tcptimeout_t) (long time);
1015 time total time spent since TCP operation started
1017 This function is called when a TCP operation times out. It is set
1018 by the SET_TIMEOUT mail_parameter(). The function can return non-zero
1019 to continue the TCP operation (e.g. after outputting a "do you still
1020 want to wait" prompt) or zero if it wants the TCP operation to abort and
1021 close. If the TCP operation aborts, it will likely cause the upper
1022 level IMAP, SMTP, etc. stream to abort and close as well.
1025 DRIVER *mail_valid (MAILSTREAM *stream,char *mailbox,char *purpose);
1026 stream if non-NIL, stream to use for validation
1027 mailbox mailbox name to validate
1028 purpose filled in as xxx in "Can't xxx" in error messages
1030 This function validates the given mailbox name. It successful, it
1031 returns the driver that can open that name if successful, otherwise it
1032 returns NIL. If stream is non-NIL, the mailbox name must be valid for
1033 the type of mailbox associated with that stream (e.g. an NNTP name can
1034 not be used with an IMAP stream). If purpose is non-NIL, an error
1035 message is passed via mm_log() when an error occurs.
1038 DRIVER *mail_valid_net (char *name,DRIVER *drv,char *host,char *mailbox);
1039 name mailbox name to validate
1040 drv driver name to validate against
1041 host buffer to return host name if non-NIL
1042 mailbox buffer to return remote mailbox name if non-NIL
1044 This function is an alternative to mail_valid_net_parse(). It
1045 validates the given mailbox name as a network name and makes sure that
1046 its service name is the same as the driver in drv. If successful, it
1047 returns drv, and copies the host and mailbox strings as needed.
1048 Otherwise it returns NIL.
1051 long mail_valid_net_parse (char *name,NETMBX *mb);
1052 name mailbox name to parse
1053 mb pointer to NETMBX structure to return
1055 This function parses a network mailbox name. If the name is a
1056 network mailbox name, it returns non-NIL, with the NETMBX structure
1057 loaded with the results form the parse.
1058 \f
1059 Mailbox Access Functions
1061 void mail_list (MAILSTREAM *stream,char *ref,char *pat);
1062 void mail_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents);
1063 stream if non-NIL, stream to use
1064 ref mailbox reference string
1065 pat mailbox pattern string
1066 contents contents to search
1068 This function returns a list of mailboxes via the mm_list()
1069 callback. The reference is applied to the pattern in an implementation
1070 dependent fashion, and the resulting string is used to search for
1071 matching mailbox names. "*" is a wildcard which matches zero or more
1072 characters; "%" is a variant which does not descend a hierarchy level.
1073 Read the IMAP specification for more information.
1075 mail_scan() is a variant which takes a string to search for in the
1076 text of the mailbox. The string is a free-text string, without regard
1077 for message boundaries, and thus the choice of strings must be made
1078 with care.
1081 void mail_lsub (MAILSTREAM *stream,char *ref,char *pat);
1082 stream if non-NIL, stream to use
1083 ref mailbox reference string
1084 pat mailbox pattern string
1086 This function returns a list of subscribed mailboxes via the
1087 mm_lsub() callback. The reference is applied to the pattern in an
1088 implementation dependent fashion, and the resulting string is used to
1089 search for matching mailbox names in the subscription list. "*" is a
1090 wildcard which matches zero or more characters; "%" is a variant which
1091 does not descend a hierarchy level. Read the IMAP specification for
1092 more information.
1095 long mail_subscribe (MAILSTREAM *stream,char *mailbox);
1096 stream if non-NIL, stream to use
1097 mailbox mailbox name
1099 This function adds the given name to the subscription list. It
1100 returns T if successful, NIL if unsuccessful. If unsuccessful, an
1101 error message is returned via the mm_log() callback.
1104 long mail_unsubscribe (MAILSTREAM *stream,char *mailbox);
1105 stream if non-NIL, stream to use
1106 mailbox mailbox name
1108 This function removes the given name from the subscription list.
1109 It returns T if successful, NIL if unsuccessful. If unsuccessful, an
1110 error message is returned via the mm_log() callback.
1113 long mail_create (MAILSTREAM *stream,char *mailbox);
1114 stream if non-NIL, stream to use
1115 mailbox mailbox name
1117 This function creates a mailbox with the given name. It returns T
1118 if successful, NIL if unsuccessful. If unsuccessful, an error message
1119 is returned via the mm_log() callback.
1121 It is an error to create INBOX or a mailbox name which already
1122 exists.
1125 long mail_delete (MAILSTREAM *stream,char *mailbox);
1126 stream if non-NIL, stream to use
1127 mailbox mailbox name
1129 This function deletes the named mailbox. It returns T if
1130 successful, NIL if unsuccessful. If unsuccessful, an error message is
1131 returned via the mm_log() callback.
1133 It is an error to delete INBOX or a mailbox name which does not
1134 already exist.
1137 long mail_rename (MAILSTREAM *stream,char *old,char *newname);
1138 stream if non-NIL, stream to use
1139 old existing mailbox name
1140 newname new (not yet existing) mailbox name
1142 This function renames the old mailbox to the new mailbox name.
1143 It returns T if successful, NIL if unsuccessful. If unsuccessful, an
1144 error message is returned via the mm_log() callback.
1146 It is an error to reanme a mailbox that does not exist, or rename
1147 a mailbox to a name that already exists. It is permitted to rename
1148 INBOX; a new empty INBOX is created in its place.
1151 long mail_status (MAILSTREAM *stream,char *mbx,long flags);
1152 stream if non-NIL, stream to use
1153 mbx mailbox name
1154 flags option flags
1156 This function returns the status of the given mailbox name via the
1157 mm_status() callback. It returns T if successful, NIL if unsuccessful.
1158 If unsuccessful, an error message is returned via the mm_log()
1159 callback.
1161 The options are a bit mask with one or more of the following,
1162 indicating the data which should be returned.
1163 SA_MESSAGES number of messages in the mailbox
1164 SA_RECENT number of recent messages in the mailbox
1165 SA_UNSEEN number of unseen messages in the mailbox
1166 SA_UIDNEXT next UID value to be assigned
1167 SA_UIDVALIDITY UID validity value
1169 Note that, depending upon implementation, some of these values may
1170 be more costly to get than others. For example, calculating the
1171 number of unseen messages may require opening the mailbox and scanning
1172 all of the message flags. A mail_status() call should thus be used
1173 with option flags specifying only the data that is actually needed.
1176 MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options);
1177 oldstream if non-NIL, stream to recycle
1178 name mailbox name to open
1179 options option flags.
1181 This function opens the mailbox and if successful returns a stream
1182 suitable for use by the other MAIL functions.
1184 If oldstream is non-NIL, an attempt is made to reuse oldstream as
1185 the stream for this mailbox; this is useful when you want to open
1186 another mailbox to the same IMAP or NNTP server without having to open
1187 a new connection. Doing this will close the previously open mailbox.
1189 The options are a bit mask with one or more of the following:
1190 OP_DEBUG Log IMAP protocol telemetry through mm_debug()
1191 OP_READONLY Open mailbox read-only.
1192 OP_ANONYMOUS Don't use or update a .newsrc file for news.
1193 OP_SHORTCACHE Don't cache envelopes or body structures
1194 OP_SILENT Don't pass mailbox events (internal use only)
1195 OP_PROTOTYPE Return the "prototype stream" for the driver
1196 associated with this mailbox instead of
1197 opening the stream
1198 OP_HALFOPEN For IMAP and NNTP names, open a connection
1199 to the server but don't open a mailbox.
1200 OP_EXPUNGE Silently expunge the oldstream before recycling
1202 NIL is returned if this function fails for any reason.
1205 MAILSTREAM *mail_close (MAILSTREAM *stream);
1206 MAILSTREAM *mail_close_full (MAILSTREAM *stream,long options);
1207 stream stream to close
1208 options option flags
1209 This function closes the MAIL stream and frees all resources
1210 associated with it that it may have created (subject to any handles
1211 existing).
1213 The options for mail_close_full() are a bit mask with one or more
1214 of the following:
1215 CL_EXPUNGE Silently expunge before closing
1217 This function always returns NIL, so it can be used as:
1218 stream = mail_close (stream);
1219 \f
1220 Handle Functions
1222 Handles are used when an entity that wishes to access the stream
1223 may survive the stream without knowing that it outlived it. For
1224 example, an object reading a message may have a handle to a stream,
1225 but the message selection object that spawned it (and which owns the
1226 stream) may have gone away. A stream can be closed or recycled while
1227 handles are pointing at it, but it is not completely freed until all
1228 handles are gone. A stream may have an arbitrary number of handles.
1231 MAILHANDLE *mail_makehandle (MAILSTREAM *stream);
1232 stream stream to make handle to
1234 This function creates and returns a handle to the stream.
1237 void mail_free_handle (MAILHANDLE **handle);
1238 handle pointer to handle to release
1240 This function frees the handle and notifies the stream that it has
1241 one fewer handle. If this is the last handle on the stream and the
1242 stream has been closed, then the stream is freed.
1245 MAILSTREAM *mail_stream (MAILHANDLE *handle);
1246 handle handle to look up
1248 This function returns the stream associated with the handle if and
1249 only if the stream still represents the same MAIL connection associated
1250 with the handle. Otherwise, NIL is returned (meaning that there is no
1251 active stream associated with this handle).
1252 \f
1253 Message Data Fetching Functions
1255 [Note!! There is an important difference between a "sequence" and a
1256 "msgno". A sequence is a string representing one or more messages in
1257 IMAP4-style sequence format ("n", "n:m", or combination of these
1258 delimited by commas), whereas a msgno is an int representing a single
1259 message.]
1261 void mail_fetchfast (MAILSTREAM *stream,char *sequence);
1262 void mail_fetchfast_full (MAILSTREAM *stream,char *sequence,long flags);
1263 stream stream to fetch on
1264 sequence IMAP-format set of message sequence numbers
1265 flags option flags
1267 This function causes a cache load of all the "fast" information
1268 (internal date, RFC 822 size, and flags) for the given sequence. Since
1269 all this information is also fetched by mail_fetchstructure(), this
1270 function is generally not used unless the OP_SHORTCACHE option in the
1271 mail_open() call is used.
1273 The options for mail_fetchfast_full() are a bit mask with one or
1274 more of the following:
1275 FT_UID The sequence argument contains UIDs instead of
1276 sequence numbers
1279 void mail_fetchflags (MAILSTREAM *stream,char *sequence);
1280 void mail_fetchflags_full (MAILSTREAM *stream,char *sequence,long flags);
1282 This function causes a fetch of the flags for the given sequence.
1283 This main reason for using this function is to update the flags in the
1284 local cache in case some other process changed the flags (multiple
1285 simultaneous write access is allowed to the flags) as part of a "check
1286 entire mailbox" (as opposed to "check for new messages") operation.
1288 The options for mail_fetchflags_full() are a bit mask with one or more
1289 of the following:
1290 FT_UID The sequence argument contains UIDs instead of
1291 sequence numbers
1294 ENVELOPE *mail_fetchenvelope (MAILSTREAM *stream,unsigned long msgno);
1295 ENVELOPE *mail_fetchstructure (MAILSTREAM *stream,unsigned long msgno,
1296 BODY **body);
1297 ENVELOPE *mail_fetchstructure_full (MAILSTREAM *stream,unsigned long msgno,
1298 BODY **body,long flags);
1299 stream stream to fetch on
1300 msgno message sequence number
1301 body pointer to where to return BODY structure if non-NIL
1302 flags option flags
1303 This function causes a fetch of all the structured information
1304 (envelope, internal date, RFC 822 size, flags, and body structure) for
1305 the given msgno and, in the case of IMAP, up to MAPLOOKAHEAD (a
1306 parameter in IMAP2.H) subsequent messages which are not yet in the
1307 cache. No fetch is done if the envelope for the given msgno is already
1308 in the cache. The ENVELOPE and the BODY for this msgno is returned.
1309 It is possible for the BODY to be NIL, in which case no information is
1310 available about the structure of the message body.
1312 The options for mail_fetchstructure_full() are a bit mask with one
1313 or more of the following:
1314 FT_UID The msgno argument is a UID
1316 This is the primary function for fetching non-text information
1317 about messages, and should be called before any attempt to reference
1318 cache information about this message via mail_elt().
1321 char *mail_fetchheader (MAILSTREAM *stream,unsigned long msgno);
1322 char *mail_fetchheader_full (MAILSTREAM *stream,unsigned long msgno,
1323 STRINGLIST *lines,unsigned long *len,long flags);
1324 stream stream to fetch on
1325 msgno message sequence number
1326 lines list of header lines to fetch
1327 len returned length in octets
1328 flags option flags
1330 This function causes a fetch of the complete, unfiltered RFC 822
1331 format header of the specified message as a text string and returns
1332 that text string.
1334 If the lines argument is non-NIL, it contains a list of header
1335 field names to use in subsetting the header text. Only those lines
1336 which have that header field name are returned, unless FT_NOT is set in
1337 which case only those lines which do not have that header field name
1338 are returned.
1340 If the len argument is non-NIL, it holds a pointer in which the
1341 length of the string in octets is returned. This is useful in cases
1342 where there may be an embedded null in the string.
1344 This function always returns a valid string pointer; if no header
1345 exists or if it can not be fetched (e.g. by a deceased IMAP stream) an
1346 empty string is returned.
1348 The options for mail_fetchheader_full() are a bit mask with one or
1349 more of the following:
1350 FT_UID The msgno argument is a UID
1351 FT_NOT The returned header lines are those that are
1352 not in the lines argument
1353 FT_INTERNAL The return string is in "internal" format,
1354 without any attempt to canonicalize to CRLF
1355 newlines
1356 FT_PREFETCHTEXT The RFC822.TEXT should be pre-fetched at the
1357 same time. This avoids an extra RTT on an
1358 IMAP connection if a full message text is
1359 desired (e.g. in a "save to local file"
1360 operation)
1363 char *mail_fetchtext (MAILSTREAM *stream,unsigned long msgno);
1364 char *mail_fetchtext_full (MAILSTREAM *stream,unsigned long msgno,
1365 unsigned long *len,long flags);
1366 stream stream to fetch on
1367 msgno message sequence number
1368 len returned length in octets
1369 flags option flags
1371 This function causes a fetch of the non-header text of the
1372 specified message as a text string and returns that text string. No
1373 attempt is made to segregate individual body parts.
1375 If the len argument is non-NIL, it holds a pointer in which the
1376 length of the string in octets is returned. This is useful in cases
1377 where there may be an embedded null in the string.
1379 This function always returns a valid string pointer; if no header
1380 exists or if it can not be fetched (e.g. by a deceased IMAP stream) an
1381 empty string is returned.
1383 The options for mail_fetchtext_full() are a bit mask with one or
1384 more of the following:
1385 FT_UID The msgno argument is a UID
1386 FT_PEEK Do not set the \Seen flag if it not already set
1387 FT_INTERNAL The return string is in "internal" format,
1388 without any attempt to canonicalize to CRLF
1389 newlines
1392 char *mail_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *sec,
1393 unsigned long *len);
1394 char *mail_fetchbody_full (MAILSTREAM *stream,unsigned long msgno,char *sec,
1395 unsigned long *len,long flags);
1396 stream stream to fetch on
1397 msgno message sequence number
1398 sec section specifier
1399 len returned length in octets
1400 flags option flags
1402 This function causes a fetch of the particular section of the
1403 body of the specified message as a text string and returns that text
1404 string. The section specification is a string of integers delimited by
1405 period which index into a body part list as per the IMAP4
1406 specification. Body parts are not decoded by this function; see
1407 rfc822_base64() and rfc822_quotedprintable().
1409 If the len argument is non-NIL, it holds a pointer in which the
1410 length of the string in octets is returned. This is useful in cases
1411 where there may be an embedded null in the string.
1413 This function may return NIL on error.
1415 The options for mail_fetchbody_full() are a bit mask with one or
1416 more of the following:
1417 FT_UID The msgno argument is a UID
1418 FT_PEEK Do not set the \Seen flag if it not already set
1419 FT_INTERNAL The return string is in "internal" format,
1420 without any attempt to canonicalize to CRLF
1421 newlines
1424 unsigned long mail_uid (MAILSTREAM *stream,unsigned long msgno);
1425 stream stream to fetch on
1426 msgno message sequence number
1428 This function returns the UID for the given message sequence
1429 number.
1432 void mail_fetchfrom (char *s,MAILSTREAM *stream,unsigned long msgno,
1433 long length);
1434 s destination string
1435 stream stream to fetch on
1436 msgno message sequence number
1437 length maximum field length
1439 This function writes a "from" string of the specified length for
1440 the specified message, suitable for display to the user in a menu line,
1441 into the string pointed to by s.
1443 If the personal name of the first address in the envelope's from
1444 item is non-NIL, it is used; otherwise a string is created by appending
1445 the mailbox of the first address, an "@", and the host of the first
1446 address. The string is trimmed or padded with trailing spaces as
1447 necessary to make its length match the length argument.
1450 void mail_fetchsubject (char *s,MAILSTREAM *stream,unsigned long msgno,
1451 long length);
1452 s destination string
1453 stream stream to fetch on
1454 msgno message sequence number
1455 length maximum field length
1457 This function returns a "subject" string of the specified length
1458 for the specified message, suitable for display to the user in a menu
1459 line.
1461 The envelope's subject item is copied and trimmed as necessary
1462 to make its length be no more what the caller requested. Unlike
1463 mail_fetchfrom(), this function can return a string of shorter length
1464 than what the caller requested.
1467 LONGCACHE *mail_lelt (MAILSTREAM *stream,unsigned long msgno);
1468 MESSAGECACHE *mail_elt (MAILSTREAM *stream,unsigned long msgno);
1469 stream stream to access
1470 msgno message sequence number
1472 This function returns the cache entry for the specified message.
1473 Although it will create a cache entry if it does not already exist,
1474 that functionality is for internal use only. This function should
1475 never be called without having first called mail_fetchfast() or
1476 mail_fetchstructure() on the message first.
1478 A cache entry holds the internal date/time, flags, and RFC 822
1479 size of a message. It holds other data as well, but that is for
1480 internal use only.
1482 mail_lelt() is a variant that returns a `long' cache entry, which
1483 consists of an cache entry (as a structure, not a pointer), an envelope
1484 pointer, and a body pointer. This is used in conjunction with the elt
1485 lock count functionality, to allow an application to associate the
1486 cached envelope and body of a message with an open window even if the
1487 message is subsequently expunged or if the stream is closed.
1489 Unless your application wants to look at cached envelopes and
1490 bodies even after the message is expunged or the stream is closed, it
1491 should not use mail_lelt(). Instead, it should use a returned elt from
1492 mail_elt() and use the elt->msgsno as the argument to
1493 mail_fetchstructure().
1495 BEWARE: the behavior of mail_lelt() is undefined if the
1496 stream is open with OP_SHORTCACHE. mail_lelt() is extremely
1497 special purpose, and should only be used in sophisticated
1498 special purpose applications after discussing its use with
1499 the c-client author. If you think you need this function,
1500 you are probably mistaken. In almost all cases, you should
1501 use mail_elt() and mail_fetchstructure() instead.
1502 \f
1503 Message Status Manipulation Functions
1505 void mail_setflag (MAILSTREAM *stream,char *sequence,char *flag);
1506 void mail_setflag_full (MAILSTREAM *stream,char *sequence,char *flag,
1507 long flags);
1508 stream stream to use
1509 sequence IMAP-format set of message sequence numbers
1510 flag IMAP-format flag string
1511 flags option flags
1513 This function causes a store to add the specified flag to the flags
1514 set for the messages in the specified sequence. If there is any
1515 problem in setting flags, a message will be passed to the application
1516 via the mm_log() facility.
1518 The options for mail_setflag_full() are a bit mask with one or
1519 more of the following:
1520 ST_UID The sequence argument contains UIDs instead of
1521 sequence numbers
1522 ST_SILENT Do not update the local cache with the new
1523 value of the flags. This is useful to save
1524 network bandwidth, at the cost of invalidating
1525 the cache.
1528 void mail_clearflag (MAILSTREAM *stream,char *sequence,char *flag);
1529 void mail_clearflag_full (MAILSTREAM *stream,char *sequence,char *flag,
1530 long flags);
1531 stream stream to use
1532 sequence IMAP-format set of message sequence numbers
1533 flag IMAP-format flag string
1534 flags option flags
1536 This function causes a store to delete the specified flag from the
1537 flags set for the messages in the specified sequence. If there is any
1538 problem in clearing flags, a message will be passed to the application
1539 via the mm_log() facility.
1541 The options for mail_setflag_full() are a bit mask with one or
1542 more of the following:
1543 ST_UID The sequence argument contains UIDs instead of
1544 sequence numbers
1545 ST_SILENT Do not update the local cache with the new
1546 value of the flags. This is useful to save
1547 network bandwidth, at the cost of invalidating
1548 the cache.
1549 \f
1550 Mailbox Searching
1552 void mail_search (MAILSTREAM *stream,char *criteria);
1553 void mail_search_full (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm,
1554 long flags);
1555 stream stream to search
1556 charset MIME character set to use when searching strings
1557 pgm search program
1558 flags option flags
1560 This function causes a mailbox search, using the given MIME
1561 charset (NIL means the default, US-ASCII) and the given search program.
1562 A search program is a structure that holds the following data:
1564 SEARCHSET *msgno; a set of message sequence numbers
1565 SEARCHSET *uid; a set of unique identifiers
1566 SEARCHOR *or; OR result of two search programs
1567 SEARCHPGMLIST *not; AND result of list of NOT'ed search programs
1568 SEARCHHEADER *header; message headers
1569 STRINGLIST *bcc; string(s) appear in bcc list
1570 STRINGLIST *body; string(s) appear in message body text
1571 STRINGLIST *cc; string(s) appear in cc list
1572 STRINGLIST *from; string(s) appear in from
1573 STRINGLIST *keyword; user flag string(s) set
1574 STRINGLIST *unkeyword; user flag strings() not set
1575 STRINGLIST *subject; string(s) appear in subject
1576 STRINGLIST *text; string(s) appear in message header or body
1577 STRINGLIST *to; string(s) appear in to list
1578 unsigned long larger; larger than this many octets
1579 unsigned long smaller; smaller than this many octes
1580 The following dates are in form:
1581 ((year - BASEYEAR) << 9) + (month << 5) + day
1582 unsigned short sentbefore;
1583 sent before this date
1584 unsigned short senton; sent on this date
1585 unsigned short sentsince;
1586 sent since this date
1587 unsigned short before; received before this date
1588 unsigned short on; received on this date
1589 unsigned short since; received since this date
1590 unsigned int answered : 1;
1591 message answered
1592 unsigned int unanswered : 1;
1593 message not answered
1594 unsigned int deleted : 1;
1595 message deleted
1596 unsigned int undeleted : 1;
1597 message not deleted
1598 unsigned int draft : 1; message is a draft
1599 unsigned int undraft : 1;
1600 message is not a draft
1601 unsigned int flagged : 1;
1602 message flagged as urgent
1603 unsigned int unflagged : 1;
1604 message not flagged as urgent
1605 unsigned int recent : 1;
1606 message recent since last parse of mailbox
1607 unsigned int old : 1; message not recent since last parse of mailbox
1608 unsigned int seen : 1; message read
1609 unsigned int unseen : 1;
1610 message not read
1612 The following auxillary structures are used by search programs:
1613 SEARCHHEADER: header line searching
1614 char *line; header line field name
1615 char *text; text header line
1616 SEARCHHEADER *next; next SEARCHHEADER in list (AND'ed)
1618 SEARCHSET: message number set
1619 unsigned long first; first number in set
1620 unsigned long last; if non-zero, last number in set
1621 SEARCHSET *next; next SEARCHSET in list (AND'ed)
1623 SEARCHOR: two search programs, OR'ed together
1624 SEARCHPGM *first; first program
1625 SEARCHPGM *second; second program
1626 SEARCHOR *next; next SEARCHOR in list
1628 SEARCHPGMLIST: list of search programs
1629 SEARCHPGM *pgm; search program (AND'd with others in list)
1630 SEARCHPGMLIST *next; next SEARCHPGM in list
1632 mail_search(), the older interface, accepts a search criteria
1633 argument as a character string in IMAP2 (RFC-1176) format. Do not try
1634 to use any IMAP4 search criteria with this interface.
1636 The application's mm_searched() function is called for each
1637 message that matches the search criteria. In addition, after the
1638 search is completed, the "fast" information (see mail_fetchfast_full()
1639 and envelopes of the searched messages are fetched (this is called
1640 pre-fetching).
1642 If there is any problem in searching, a message will be passed to
1643 the application via the mm_log() facility.
1645 The flags for mail_search_full() are a bit mask with one or more
1646 of the following:
1647 SE_UID Return UIDs instead of sequence numbers
1648 SE_FREE Return the search program to free storage after
1649 finishing
1650 SE_NOPREFETCH Don't prefetch searched messages.
1653 unsigned long *mail_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg,
1654 SORTPGM *pgm,long flags);
1655 stream stream to sort
1656 charset MIME character set to use when sorting strings
1657 spg search program
1658 pgm sort program
1659 flags option flags
1662 This function is a variant of mail_search_full(). It accepts an
1663 additional argument, a sort program, which specifies one or more sort
1664 rules to be applied to the result. If the searching and sorting are
1665 successful, it returns a 0-terminated vector of message sequence
1666 numbers (or UIDs if SE_UID is set). This vector is created out of
1667 free storage, and must be freed with fs_give() when finished with it.
1669 A sort program is a structure that holds the following data:
1670 unsigned int reverse : 1;
1671 reverse sorting of this key
1672 short function; sort rule, one of the following:
1673 SORTDATE message Date
1674 SORTARRIVAL arrival date
1675 SORTFROM mailbox in first From address
1676 SORTSUBJECT message Subject
1677 SORTTO mailbox in first To address
1678 SORTCC mailbox in first cc address
1679 SORTSIZE size of message in octets
1680 SORTPGM *next; next sort program to be applied if two or more
1681 messages collate identically with this rule
1683 The flags for mail_search_full() are a bit mask with one or more
1684 of the following:
1685 SE_UID Return UIDs instead of sequence numbers
1686 SE_FREE Return the search program to free storage after
1687 finishing
1688 SE_NOPREFETCH Don't prefetch searched messages.
1689 SO_FREE Return the sort program to free storage after
1690 finishing
1691 \f
1692 Miscellaneous Mailbox and Message Functions
1694 long mail_ping (MAILSTREAM *stream);
1695 stream string to ping
1697 The function pings the stream to see if it is still active. It may
1698 discover new mail; this is the preferred method for a periodic "new mail
1699 check" as well as a "keep alive" for servers which have an inactivity
1700 timeout. It returns T if the stream is still alive, NIL otherwise.
1702 If new mail is found, the application's mm_exists() function is
1703 called with the newly-determined number of messages in the mailbox.
1706 void mail_check (MAILSTREAM *stream);
1707 stream stream to checkpoint
1709 This function causes a mailstore-defined checkpoint of the
1710 mailbox. This may include such things as a writeback to disk, a check
1711 for flag changes in a shared mailbox, etc. It is not a "check for new
1712 mail"; mail_ping() performs this function (as potentially does any other
1713 function). The status of the check is passed to the application via the
1714 mm_log() facility.
1717 void mail_expunge (MAILSTREAM *stream);
1718 stream string to expunge
1720 This function causes an expunge (permanent removal of messages
1721 which are marked as deleted) of the mailbox. The application's
1722 mm_expunged() function is called for each message that has been
1723 expunged. The application's mm_exists() function is called at the start
1724 and end of the expunge to ensure synchronization. The status of the
1725 expunge is passed to the application via the mm_log() facility.
1727 Note that the decrementing of msgno's for subsequent messages
1728 happens immediately; for example, if three consequtive messages starting
1729 at msgno 5 are expunged, mm_expunged() will be called with a msgno of 5
1730 three times.
1733 long mail_copy (MAILSTREAM *stream,char *sequence,char *mailbox);
1734 long mail_move (MAILSTREAM *stream,char *sequence,char *mailbox);
1735 long mail_copy_full (MAILSTREAM *stream,char *sequence,char *mailbox,
1736 long options);
1737 stream stream to copy
1738 sequence IMAP-format set of message numbers
1739 mailbox destination mailbox name
1740 options option flags
1742 This function causes the messages in the specified sequence to be
1743 copied to the specified mailbox. T is returned if the copy is
1744 successful. mail_move() is equivalent to setting CP_MOVE in the options.
1746 If there is any problem in copying, a message will be passed to
1747 the application via the mm_log() facility and the function returns NIL.
1748 No copying is actually done in this case.
1750 Note that the mailbox must be on the same host as the stream and
1751 is a mailbox of the type of the source mailbox only.
1753 The flags for mail_search_full() are a bit mask with one or more
1754 of the following:
1755 CP_UID The sequence argument contains UIDs instead of
1756 sequence numbers
1757 CP_MOVE Delete the messages from the current mailbox
1758 after copying to the destination.
1761 long mail_append (MAILSTREAM *stream,char *mailbox,STRING *message);
1762 long mail_append_full (MAILSTREAM *stream,char *mailbox,char *flags,char *date,
1763 STRING *message);
1764 stream stream to use if non-NIL (in the IMAP case)
1765 mailbox destination mailbox name
1766 flags flags to set on message if non-NIL
1767 date internal date (received date) to set on message if non-NIL
1768 message string structure of message to write
1770 This function writes the message in the string structure to the
1771 destination mailbox, along with the flags and date if specified. This
1772 is useful in those cases where you can't use mail_copy(), e.g. when
1773 copying from one server to another; you can always fetch the message
1774 and then mail_append() it to the destination. It may also be useful
1775 for maintaining an outbox of your outgoing mail.
1778 void mail_gc (MAILSTREAM *stream,long gcflags);
1779 stream stream to GC if non-NIL (else GC's all streams)
1780 flags option flags
1782 This function garbage collects (purges) the cache of entries of
1783 a specific type. Some drivers do not allow purging of particular
1784 cache types, and an attempt to do so is ignored.
1786 The flags for mail_gc() are a bit mask with one or more of the
1787 following:
1788 GC_ELT message cache elements
1789 GC_ENV ENVELOPEs and BODYs
1790 GC_TEXTS cached texts
1791 \f
1792 Date/Time Handling Functions
1795 char *mail_date (char *string,MESSAGECACHE *elt);
1796 string destination string
1797 elt message cache element containing date
1799 This function accepts a message cache element that contains date
1800 information, and writes an IMAP-4 date string, that is, one in form:
1801 dd-mmm-yyyy hh:mm:ss +zzzz
1802 based upon the data in the elt. The destination string must be large
1803 enough to hold this string.
1806 char *mail_cdate (char *string,MESSAGECACHE *elt);
1807 string destination string
1808 elt message cache element containing date
1810 This function accepts a message cache element that contains date
1811 information, and writes a ctime() format date string, that is, one in
1812 form:
1813 www mmm dd hh:mm:ss yyyy\n
1814 based upon the data in the elt. The destination string must be large
1815 enough to hold this string.
1818 long mail_parse_date (MESSAGECACHE *elt,char *string);
1819 elt message cache element to store parsed date
1820 string source date string
1822 This function parses the date/time stored in the given string,
1823 in format:
1824 [www,] date [[hh:mm[:ss][-zzz| +zzzz]
1825 where the date can be any of:
1826 mm/dd/yy, mm/dd/yyyy, dd-mmm-yy, dd-mmm-yyyy, dd mmm yy, dd mmm yyyy
1827 and stores the result of the parse in the elt. If the parse is
1828 successful, T is returned, else NIL.
1831 unsigned long mail_longdate (MESSAGECACHE *elt);
1832 elt message cache element containing date.
1834 This function accepts a message cache element that contains date
1835 information, and returns the number of days since the base time of the
1836 imap-4 toolkit. At present, this is the same as the Unix time() value
1837 for that date/time, and hence can be used for functions such as utime().
1838 \f
1839 Utility Functions
1841 void mail_debug (MAILSTREAM *stream);
1842 stream stream to debug
1844 This function enables telemetry logging for this stream. All
1845 telemetry is passed to the application via the mm_dlog() facility.
1848 void mail_nodebug (MAILSTREAM *stream);
1849 stream stream to disable debugging
1851 This function disables telemetry logging for this stream.
1854 long mail_sequence (MAILSTREAM *stream,char *sequence);
1855 stream stream to set the sequence bits
1856 sequence IMAP-format message set string
1858 This function parses the given sequence string for message
1859 numbers, sets the sequence bit in the stream's message cache element
1860 of all messages in the sequence (and turns it off in all other message
1861 cache elements). If the parse is successful, T is returned, else NIL.
1864 long mail_uid_sequence (MAILSTREAM *stream,char *sequence);
1865 stream stream to set the sequence bits
1866 sequence IMAP-format message set string
1868 This function parses the given sequence string for unique
1869 identifiers, sets the sequence bit in the stream's message cache
1870 element of all messages in the sequence (and turns it off in all other
1871 message cache elements). If the parse is successful, T is returned,
1872 else NIL.
1875 long mail_parse_flags (MAILSTREAM *stream,char *flag,unsigned long *uf);
1876 stream stream (used to get user flags)
1877 flag IMAP-format flag string to parse
1878 uf returned location of user flags
1880 The function parses the given flag string, and returns the system
1881 flags as its return value and the user flags in the location pointed
1882 to by the uf argument. If there is an error in parse, a log message
1883 is issued via mm_log() and this function returns NIL.
1886 unsigned long mail_filter (char *text,unsigned long len,STRINGLIST *lines,
1887 long flags);
1888 text RFC 822 text to filter
1889 len length in octets in the text argument
1890 lines string list of header file names to filter
1891 flags option flags
1893 This function supports the header lines filtering function of
1894 mail_fetchheader_full(). The lines argument contains a list of header
1895 field names to use in subsetting the header text. Only those lines
1896 which have that header field name are returned, unless FT_NOT is set
1897 in which case only those lines which do not have that header field
1898 name are returned.
1900 The options for mail_filter() are a bit mask with one or more of
1901 the following:
1902 FT_NOT The returned header lines are those that are
1903 not in the lines argument
1906 long mail_search_msg (MAILSTREAM *stream,unsigned long msgno,char *charset,
1907 SEARCHPGM *pgm);
1908 stream stream to search
1909 msgno message number of message to inspect
1910 charset character set of search strings
1911 pgm search program to test
1913 This function implements mail_search_full() locally in cases when
1914 it is not done by a server (e.g. local mail files, NNTP/POP). It
1915 inspects the given message on that stream to see if it matches the
1916 criteria or not. If it matches, T is returned, else NIL.
1919 SEARCHPGM *mail_criteria (char *criteria);
1920 criteria IMAP2-format search criteria string
1922 This function accepts an IMAP2-format search criteria string and
1923 parses it. If the parse is successful, it returns a search program
1924 suitable for use in mail_search_full().
1925 WARNING: This function does not accept IMAP4 search criteria.
1926 The source string must be writeable (this restriction was also
1927 in the old IMAP2 c-client).
1928 \f
1929 Data Structure Instantiation/Destruction functions
1931 These functions are used to obtain structures from free storage and
1932 to release them.
1934 ENVELOPE *mail_newenvelope (void);
1935 ADDRESS *mail_newaddr (void);
1936 BODY *mail_newbody (void);
1937 BODY *mail_initbody (BODY *body);
1938 PARAMETER *mail_newbody_parameter (void);
1939 PART *mail_newbody_part (void);
1940 STRINGLIST *mail_newstringlist (void);
1941 SEARCHPGM *mail_newsearchpgm (void);
1942 SEARCHHEADER *mail_newsearchheader (char *line);
1943 SEARCHSET *mail_newsearchset (void);
1944 SEARCHOR *mail_newsearchor (void);
1945 SEARCHPGMLIST *mail_newsearchpgmlist (void);
1946 SORTPGM *mail_newsortpgm (void);
1948 These functions, all named mail_new...(), create a new structure of
1949 the given type and initialize all of its elements to zero or empty.
1951 void mail_free_body (BODY **body);
1952 void mail_free_body_parameter (PARAMETER **parameter);
1953 void mail_free_body_part (PART **part);
1954 void mail_free_cache (MAILSTREAM *stream);
1955 void mail_free_elt (MESSAGECACHE **elt);
1956 void mail_free_lelt (LONGCACHE **lelt);
1957 void mail_free_envelope (ENVELOPE **env);
1958 void mail_free_address (ADDRESS **address);
1959 void mail_free_stringlist (STRINGLIST **string);
1960 void mail_free_searchpgm (SEARCHPGM **pgm);
1961 void mail_free_searchheader (SEARCHHEADER **hdr);
1962 void mail_free_searchset (SEARCHSET **set);
1963 void mail_free_searchor (SEARCHOR **orl);
1964 void mail_free_searchpgmlist (SEARCHPGMLIST **pgl);
1965 void mail_free_sortpgm (SORTPGM **pgm);
1967 These functions, all named mail_free_...(), take a pointer to a
1968 structure pointer, free all contained strings and structures within the
1969 structure, and finally free the structure itself and set its pointer to
1970 NIL. For example, mail_free_envelope() frees all the ADDRESS structures
1971 contained in the envelope.
1973 Normally, mail_free_elt() and mail_free_lelt() are used only if the
1974 main program has a private pointer to cache elements. If so, it is
1975 expected to increment the cache element's lockcount when it makes a
1976 private pointer, and to call this function when it is finished with it.
1977 \f
1978 Authentication Functions
1980 char *mail_auth (char *mechanism,authresponse_t resp,int argc,char *argv[]);
1981 mechanism authentication mechanism name
1982 resp callback function for providing responses
1983 argc main() function argc value
1984 argv main() function argv value
1986 This server function searches the list of authenticators that was
1987 established by auth_link() for an authenticator with the given name. If
1988 an authenticator is found, authentication is initialized. The function
1989 pointed to by resp is called as the authenticator requires responses.
1992 AUTHENTICATOR *mail_lookup_auth (unsigned int i);
1993 i position in authenticator list
1995 This function returns the nth authenticator in the list, where n is
1996 the value of it.
1999 unsigned int mail_lookup_auth_name (char *mechanism);
2000 mechanism authentication mechanism name
2002 This function searches the list of authenticators for an
2003 authenticator with the given name, and returns its position in the
2004 authenticator list.
2007 The functions below are provided by c-client client drivers or by
2008 servers to support the protocol-dependent parts of authentication.
2010 typedef void *(*authchallenge_t) (void *stream,unsigned long *len);
2011 stream stream to read challenge
2012 len pointer to returned length in octets
2014 This driver function is called by an authenticator to read a
2015 challenge from the given protocol stream in a protocol-dependent way.
2016 It returns that challenge in binary and its length in octets to the
2017 authenticator.
2020 typedef long (*authrespond_t) (void *stream,char *s,unsigned long size);
2021 stream stream to send response
2022 s response string
2023 size length of response string in octets
2025 This driver function is called by an authenticator to send a
2026 challenge response to the given stream in a protocol-dependent way.
2027 It returns T if successful, NIL if failure.
2030 typedef char *(*authresponse_t) (void *challenge,unsigned long clen,
2031 unsigned long *rlen);
2032 challenge challenge string
2033 clen length of challenge string in octets
2034 rlen pointer to returned length of response string
2036 This server function is called with a challenge string of clen
2037 octets. It sends, according to whatever protocol (IMAP, POP, etc.) it
2038 uses, and returns the received response and response length in octets.
2041 typedef long (*authclient_t) (authchallenge_t challenger,
2042 authrespond_t responder,NETMBX *mb,void *s,
2043 unsigned long trial);
2044 challenger pointer to protocol-dependent challenge reader function
2045 responder pointer to protocol-dependent response sender function
2046 mb NETMBX struct of the mailbox desired to open
2047 s stream for protocol-dependent routines to use
2048 trial number of authentication attempts remaining
2050 This client authenticator function negotiates reading challenges
2051 and sending responses for a particular authenticator (Kerberos, etc.)
2052 over the protocol, and returns T if authenticated or NIL if failed.
2055 typedef char *(*authserver_t) (authresponse_t responder,int argc,char *argv[]);
2056 responder pointer to protocol-dependent responder function
2057 argc main() function argc value
2058 argv main() function argv value
2060 This server authenticator function negotiates sending challenges and
2061 reading responses for a particular authenticator (Kerberos, etc.), and
2062 returns either the authenticated user name or NIL if authentication
2063 failed.
2064 \f
2065 Network Access Functions
2067 These functions provide a layer of indirection between the TCP
2068 routines and upper level routines. This makes it possible to insert
2069 additional code (e.g. privacy or checksum handling).
2071 NETSTREAM *net_open (char *host,char *service,unsigned long port);
2072 host host name
2073 service contact service name
2074 port contact port number
2076 This function opens a TCP connection to the given host and service
2077 or port.
2080 NETSTREAM *net_aopen (NETMBX *mb,char *service,char *usrbuf);
2081 NETMBX parsed mailbox specification
2082 service stream to open (at present, only /etc/rimapd is used)
2083 usrbuf buffer to return login user name
2085 This function attempts to open a preauthenticated connection to the
2086 given mailbox and service. It will return the login user name of the
2087 preauthenticated connection, as well as an open network stream, if
2088 successful.
2091 char *net_getline (NETSTREAM *stream);
2092 stream network stream to read
2094 This routine reads a text line from the stream. It calls
2095 stream->dtb->getline, which normally points to tcp_getline() but can be
2096 set to some other function.
2099 long net_getbuffer (void *stream,unsigned long size,char *buffer);
2100 stream network stream to read
2101 size length of data in octets
2102 buffer buffer of at least size octets
2104 This routine reads data from the stream. It calls
2105 stream->dtb->getbuffer, which normally points to tcp_getbuffer() but can
2106 be set to some other function.
2109 long net_soutr (NETSTREAM *stream,char *string);
2110 stream network stream to write
2111 string null-terminated string to output
2113 This routine writes a null-terminated string to the stream. It
2114 calls stream->dtb->soutr, which normally points to tcp_soutr() but can
2115 be set to some other function.
2118 long net_sout (NETSTREAM *stream,char *string,unsigned long size);
2119 stream network stream to write
2120 string string to output
2121 size length of string in octets
2123 This routine writes a string of length size to the stream. It
2124 calls stream->dtb->sout, which normally points to tcp_sout() but can be
2125 set to some other function.
2128 void net_close (NETSTREAM *stream);
2129 stream stream to close
2131 This routine closes the stream. It calls stream->dtb->close, which
2132 normally points to tcp_close() but can point to some other function.
2135 char *net_host (NETSTREAM *stream);
2136 stream stream to inspect
2138 This routine returns the remote host name of the stream. It calls
2139 stream->dtb->host, which normally points to tcp_host() but can point
2140 to some other function.
2143 unsigned long net_port (NETSTREAM *stream);
2144 stream stream to inspect
2146 This routine returns the remote port number of the stream. It calls
2147 stream->dtb->port, which normally points to tcp_port() but can point
2148 to some other function.
2151 char *net_localhost (NETSTREAM *stream);
2152 stream stream to inspect
2154 This routine returns the local host name of the stream. It calls
2155 stream->dtb->localhost, which normally points to tcp_localhost() but can
2156 point to some other function.
2157 \f
2158 Subscription Management Functions
2160 long sm_subscribe (char *mailbox);
2161 mailbox mailbox name to subscribe
2163 This function adds the given mailbox name to the local subscription
2164 list, and returns T if successful, NIL if failure.
2167 long sm_unsubscribe (char *mailbox);
2168 mailbox mailbox name to unsubscribe
2170 This function removes the given mailbox name from the local
2171 subscription list, and returns T if successful, NIL if failure.
2173 char *sm_read (void **sdb);
2174 sdb data to use in subsequent calls, or NIL if first call
2176 This function returns the local subscription list as null
2177 terminated strings. Each call returns the next element in the list.
2178 The first call should be with sdb pointing to a NIL pointer; this will
2179 be filled in for subsequent calls. At the last call, NIL will be
2180 returned.
2181 \f
2182 Miscellaneous Utility Functions
2184 char *ucase (char *string);
2185 string string to convert
2187 This function converts each lowercase character of the specified
2188 string to uppercase and returns the string.
2191 char *lcase (char *string);
2192 string string to convert
2194 This function converts each uppercase character of the specified
2195 string to lowercase and returns the string.
2198 char *cpystr (char *string);
2199 string string to copy
2201 This function makes a copy of the string from free storage and returns
2202 the copy.
2205 long find_rightmost_bit (long *valptr);
2206 valptr pointer to value to search
2208 This function returns -1 if the 32-bit value pointed to by valptr
2209 is non-zero, otherwise it returns the bit number (0 = LSB, 31 = MSB) of
2210 the right-most bit in that value. This is used to convert from the bits
2211 in the cache's userflags item to an index into the stream's userFlags
2212 array of flag texts.
2215 long min (long i,long j);
2216 i first argument
2217 j second argument
2219 This function returns the minimum of the two integers.
2221 long max (long i,long j);
2222 i first argument
2223 j second argument
2225 This function returns the maximum of the two integers.
2227 long search (char *s,long c,char *pat,long patc);
2228 s string to search
2229 c size of string
2230 pat pattern to search in string
2231 patc size of pattern
2233 This function does a fast case-independent search for the given
2234 pattern in pat (length patc) in base string s, and returns T if the
2235 pattern is found in the string.
2238 long pmatch (char *s,char *pat,delim);
2239 long pmatch_full (char *s,char *pat,delim);
2240 s string to match
2241 pat wildcard (* and %) to match in pattern
2242 delim hierarchy delimiter
2244 This function returns T if the given wildcard pattern matches the
2245 string in s with hierarchy delimiter delim. Otherwise NIL is returned.
2248 long dmatch (char *s,char *pat,char delim);
2249 s string to match
2250 pat wildcard (* and %) to match in pattern
2251 delim hierarchy delimiter
2253 This function returns T if the given wildcard pattern matches the
2254 directory. If not, then none of the elements in the directory are
2255 considered for recursive checking with pmatch_full().
2256 \f
2257 SMTP Functions
2259 SMTPSTREAM *smtp_open (char **hostlist,long debug);
2260 hostlist vector of SMTP server host names to try
2261 debug non-zero if want protocol telemetry debugging
2263 This function opens an SMTP connection to a one of the hosts in the
2264 host list and if successful returns a stream suitable for use by the
2265 other SMTP functions. The hosts are tried in order until a connection is
2266 successfully opened. If debug is non-NIL, protocol telemetry is logged
2267 via mm_dlog(). NIL is returned if this function fails to open a
2268 connection to any of the hosts in the list.
2270 void smtp_close (SMTPSTREAM *stream);
2271 stream stream to close
2273 This function closes the SMTP stream and frees all resources
2274 associated with it that it may have created.
2276 long smtp_mail (SMTPSTREAM *stream,char *type,ENVELOPE *msg,BODY *body);
2277 stream stream to transmit mail
2278 type mail type (MAIL, SEND, SAML, SOML)
2279 msg message envelope
2280 body message body
2282 This function negotiates an SMTP transaction of the specified type
2283 (one of "MAIL", "SEND", "SAML", or "SOML") to deliver the specified
2284 message. This function returns T if success or NIL if there is any
2285 failure. The text reason for the failure is in stream->reply item; if
2286 it is associated with a recipient it is also in that address'
2287 address->error item.
2290 void smtp_debug (SMTPSTREAM *stream);
2291 stream stream to enable debugging telemetry
2293 This function enables SMTP protocol telemetry logging for this
2294 stream. All SMTP protocol operations are passed to the application via
2295 the mm_dlog() facility.
2298 void smtp_nodebug (SMTPSTREAM *stream);
2299 stream stream to disable debugging telemetry
2301 This function disables SMTP protocol telemetry logging for this
2302 stream.
2305 typedef void (*smtpverbose_t) (char *buffer);
2306 buffer pointer to verbose reply buffer
2308 This is the argument to the SET_SMTPVERBOSE mail_parmameter() call.
2309 If this function pointer is non-NIL, then if a verbose SMTP response
2310 (with SMTP code less than 100) is received, this function is called with
2311 that response text as its argument.
2312 \f
2313 NNTP Functions
2315 NNTPSTREAM *nntp_open (char **hostlist,long debug);
2316 hostlist vector of NNTP server host names to try
2317 debug non-zero if want protocol telemetry debugging
2319 This function opens an NNTP connection to a one of the hosts in the
2320 host list and if successful returns a stream suitable for use by the
2321 other MTP functions. The hosts are tried in order until a connection is
2322 successfully opened. If debug is non-NIL, protocol telemetry is logged
2323 via mm_dlog(). NIL is returned if this function fails to open a
2324 connection to any of the hosts in the list.
2327 void nntp_close (NNTPSTREAM *stream);
2328 stream stream to close
2330 This function closes the NNTP stream and frees all resources
2331 associated with it that it may have created.
2334 long nntp_mail (NNTPSTREAM *stream,ENVELOPE *msg,BODY *body);
2335 stream stream to transmit mail
2336 msg message envelope
2337 body message body
2339 This function negotiates an NNTP posting transaction to deliver
2340 the specified news message. This function returns T if success or NIL
2341 if there is any failure. The text reason for the failure is in
2342 stream->reply item; if it is associated with a recipient it is also in
2343 that address' address->error item.
2344 \f
2345 RFC 822 Support Functions
2347 Although rfc822.c contains several additional functions besides
2348 these, only the functions documented here should be used by
2349 applications. The other functions are for internal use only.
2352 void rfc822_header (char *header,ENVELOPE *env,BODY *body);
2353 header buffer to write RFC 822 header
2354 env message ENVELOPE (used to obtain RFC 822 information)
2355 body message BODY (used to obtain MIME information)
2357 This function writes an RFC 822 format header into header based
2358 on the information in the envelope and body. The header buffer must
2359 be large enough to contain the full text of the resulting header.
2362 void rfc822_write_address (char *dest,ADDRESS *adr);
2363 dest buffer to write address list
2364 adr RFC 822 ADDRESS list
2366 This function writes an RFC 822 format address list into dest
2367 based on the information in adr. The dest buffer must be large enough
2368 to contain the full text of the resulting address list.
2370 void rfc822_parse_msg (ENVELOPE **en,BODY **bdy,char *s,unsigned long i,
2371 STRING *b,char *host,char *tmp);
2372 en destination pointer where message ENVELOPE will be stored
2373 bdy destination pointer where message BODY will be stored
2374 s RFC 822 header to parse (character string)
2375 i length of RFC 822 header
2376 b stringstruct of message body
2377 host default host name if an address lacks an @host.
2378 temp scratch buffer, must be long enough to hold unwound
2379 header lines (a buffer that is i octets long is OK)
2381 This function parses the RFC 822 header pointed to by s with body
2382 pointed to by string structure b into the specified destination
2383 envelope and body pointers, using host as the default host name and
2384 tmp as a scratch buffer. New ENVELOPE and BODY structures are
2385 created; when finished with them the application must free them with
2386 mail_free_envelope() and mail_free_body(). Any parsing errors are
2387 noted via the mm_log() mechanism using log type PARSE.
2390 void rfc822_parse_adrlist (ADDRESS **lst,char *string,char *host);
2391 lst destination pointer where ADDRESS will be stored
2392 string string of addresses to parse
2393 host default host name if an address lacks an @host.
2395 This function parses the address list in the given string into an
2396 address list in lst. Any addresses missing a host name are have the
2397 host name defaulted from the host argument. If the destination list
2398 is non-empty it appends the new addresses to the list. Any parsing
2399 errors are noted via the mm_log() mechanism using log type PARSE.
2401 long rfc822_output (char *t,ENVELOPE *env,BODY *body,soutr_t f,void *s,
2402 long ok8bit);
2403 t scratch buffer, large enough to hold message header
2404 env message ENVELOPE
2405 body message BODY
2406 f I/O function to write to
2407 s stream for I/O function f
2408 ok8bit non-zero if OK to output 8-bit data
2410 This function writes the message described with the given
2411 envelope and body. Any body part contents of type ENCBINARY is
2412 converted to ENCBASE64 before sending. If ok8bit is NIL, any message
2413 data of type ENC8BIT is converted to ENCQUOTEDPRINTABLE before
2414 sending; if ok8bit is non-NIL then ENC8BIT data is sent as-is. T is
2415 returned if the function succeeds, else NIL is returned.
2417 The function f is typically net_soutr(), but it can be any
2418 function which matches
2419 typedef long (*soutr_t) (void *stream,char *string);
2420 where stream holds sufficient information to enable the output routine
2421 to know where to output to, and the string is a null-terminated string
2422 to output. This function returns either T or NIL, and that value is
2423 passed up to rfc822_output() for its return.
2426 void *rfc822_base64 (char *src,unsigned long srcl,unsigned long *len);
2427 src source string
2428 srcl size of source string in octets
2429 len pointer to where destination string length in octets
2430 will be returned
2432 This function decodes a BASE64 body part given a source string
2433 and its length. The decoded body part as a sequence of binary octets
2434 is returned, and its length is returned in len.
2437 char *rfc822_qprint (char *src,unsigned long srcl,unsigned long *len);
2438 src source string
2439 srcl size of source string in octets
2440 len pointer to where destination string length in octets
2441 will be returned
2443 This function decodes a QUOTED-PRINTABLE body part given a source
2444 string and its length. The decoded body part as an 8-bit character
2445 string is returned, and its length is returned in len.
2446 \f
2447 Operating System-Dependent Public Interface
2449 These functions are in OS-dependent code, and are rewritten each
2450 time c-client is ported to a new operating system.
2453 void rfc822_date (char *date);
2454 date buffer to write the date, must be large enough
2456 This function is called to get the current date and time in an
2457 RFC 822 format string into the given buffer.
2460 void *fs_get (size_t size);
2461 size number of octets requested
2463 This function allocates and returns a block of free storage of
2464 the specified size. Unlike malloc(), there is no failure return; this
2465 function must return with the requested storage.
2468 void fs_resize (void **block,size_t size);
2469 block pointer to pointer to block to be resized
2470 size new size in octets
2472 This function resizes the free storage block, updating the
2473 pointer if necessary. Unlike realloc(), there is no failure return;
2474 this function must return with the requested storage.
2477 void fs_give (void **block);
2478 block pointer to pointer to block to free
2480 This function releases a block of free storage allocated by
2481 fs_get(). It also erases the block pointer, so it isn't necessary to
2482 do this in the application.
2485 void fatal (char *string);
2486 string message string
2488 This function is called when an "impossible" error is detected
2489 and the client wishes to crash. The string should contain a reason.
2492 char *strcrlfcpy (char **dst,long *dstl,char *src,long srcl);
2493 dst pointer to destination string pointer
2494 dstl pointer to destination string size
2495 src source strin
2496 srcl source string size
2498 This function is called to copy into a destination string dst of
2499 size dstl (resized if necessary), a CRLF newline form string from
2500 local format string src of size srcl.
2503 TCPSTREAM *tcp_open (char *host,long port);
2504 TCPSTREAM *tcp_aopen (char *host,char *service);
2505 char *tcp_getline (TCPSTREAM *stream);
2506 long tcp_getbuffer (TCPSTREAM *stream,long size,char *buffer);
2507 long tcp_soutr (TCPSTREAM *stream,char *string);
2508 void tcp_close (TCPSTREAM *stream);
2509 char *tcp_host (TCPSTREAM *stream);
2510 unsigned long tcp_port (TCPSTREAM *stream);
2511 char *tcp_localhost (TCPSTREAM *stream);
2513 These functions are TCP-specific versions of the more general
2514 net_xxx() functions. These should not be called directly by
2515 applications.
2518 char *tcp_clienthost (char *dst);
2519 dst destination string buffer
2521 This function should be called only by a server called by inetd
2522 or similar mechanism which maps standard input to a network socket.
2523 It returns the host name of the other end (e.g. the client of a
2524 server) using the given string buffer, or NIL if it can't get this
2525 information.
2526 \f
2527 Main Program Callbacks
2529 All applications which use the c-client must have the following
2530 callbacks to handle events from c-client. Note that in any callback
2531 which involves a mail stream, the stream is locked and you can not
2532 recursively call c-client from the callback. This may also be true in
2533 callbacks which do not have a stream; in general, the rule is "do not
2534 call c-client, especially any mail_xxx() function, from a c-client
2535 callback".
2538 void mm_flags (MAILSTREAM *stream,unsigned long number);
2539 stream stream where event happened
2540 number message number
2542 This function is called when c-client manipulates the flags for
2543 the given message number. This alerts the application that it may
2544 need to inspect that message's flags to see if there are any
2545 interesting changes.
2548 void mm_status (MAILSTREAM *stream,char *mailbox,MAILSTATUS *status);
2549 stream stream where event happened
2550 mailbox mailbox name for this status
2551 status MAILSTATUS structure with message status
2553 This function is called when c-client reports status of a mailbox
2554 (generally as the result of a mail_status() function call). The
2555 returned MAILSTATUS structure has the following members:
2557 long flags; validity flags. These are the same as
2558 the SA_xxx option flags in the
2559 mail_status() call, and they indicate
2560 which of the other members of the
2561 MAILSTATUS structure have usable data
2562 (i.e. if SA_MESSAGES is not set, do
2563 not believe status->messages!!).
2564 unsigned long messages; number of messages if SA_MESSAGES
2565 unsigned long recent; number of recent messages if SA_RECENT
2566 unsigned long unseen; number of unseen messages if SA_UNSEEN
2567 unsigned long uidnext; next UID to be assigned if SA_UIDNEXT
2568 unsigned long uidvalidity; UID validity value if SA_UIDVALIDITY
2571 void mm_searched (MAILSTREAM *stream,unsigned long number);
2572 stream stream where event happened
2573 number message number
2575 This function is called to notify the main program that this
2576 message number matches a search (generally as the result of a
2577 mail_search_full() function call).
2580 void mm_exists (MAILSTREAM *stream,unsigned long number);
2581 stream stream where event happened
2582 number message number
2584 This function is called to notify the main program that there are
2585 this many messages in the mailbox. It is also used to notify the main
2586 program of new mail, by announcing a higher number than the main
2587 program was previously aware.
2590 void mm_expunged (MAILSTREAM *stream,unsigned long number);
2591 stream stream where event happened
2592 number message number
2594 This function is called to notify the main program that this
2595 message number has been expunged from the mail file and that all
2596 subsequent messages are now referenced by a message number one less
2597 than before. This implicitly decrements the number of messages in the
2598 mailbox.
2601 void mm_list (MAILSTREAM *stream,char delim,char *name,long attrib);
2602 stream stream where event happened
2603 delim hierarchy delimiter
2604 name mailbox name
2605 attrib mailbox attributes
2607 This function is called to notify the main program that this
2608 mailbox name matches a mailbox listing request (generally as the
2609 result of a mail_list() function call). The hierarchy delimiter is a
2610 character that separates out levels of hierarchy in mailbox names.
2611 The attributes are a bit mask with one of the following:
2612 LATT_NOINFERIORS
2613 it is not possible for there to be any
2614 hierarchy inferiors to this name (that is,
2615 this name followed by the hierarchy delimiter
2616 and additional name characters).
2617 LATT_NOSELECT this is not a mailbox name, just a hierarchy
2618 level, and it may not be opened by mail_open()
2619 LATT_MARKED this mailbox may have recent messages
2620 LATT_UNMARKED this mailbox does not have any recent messages
2623 void mm_lsub (MAILSTREAM *stream,char delim,char *name,long attrib);
2624 stream stream where event happened
2625 delim hierarchy delimiter
2626 name mailbox name
2627 attrib mailbox attributes
2630 This function is called to notify the main program that this
2631 mailbox name matches a subscribed mailbox listing request (generally
2632 as the result of a mail_lsub() function call). The hierarchy
2633 delimiter is a character that separates out levels of hierarchy in
2634 mailbox names. The attributes are a bit mask with one of the
2635 following:
2636 LATT_NOINFERIORS
2637 it is not possible for there to be any
2638 hierarchy inferiors to this name (that is,
2639 this name followed by the hierarchy delimiter
2640 and additional name characters).
2641 LATT_NOSELECT this is not a mailbox name, just a hierarchy
2642 level, and it may not be opened by mail_open()
2643 LATT_MARKED this mailbox may have recent messages
2644 LATT_UNMARKED this mailbox does not have any recent messages
2647 void mm_notify (MAILSTREAM *stream,char *string,long errflg);
2648 stream stream where event happened
2649 string message string
2650 errflg message error level
2652 This function is called to deliver a stream-oriented message
2653 event. This is the mechanism by which any IMAP response codes for any
2654 application (e.g. TRYCREATE) are delivered to the application.
2655 No newline is included in the string, so this function has to output
2656 its own.
2658 The message error level is one of the following:
2660 NIL normal operation. The text is `babble' that may be
2661 interesting to the user, e.g. the greeting message
2662 from a server.
2664 WARN A warning event. This event should be displayed to
2665 the user. Examples: a mailbox rewrite failed because
2666 of disk full, but the previous mailbox contents were
2667 recovered.
2669 ERROR An error event. This event should be displayed to
2670 the user, or at least logged someplace. This type of
2671 error shouldn't happen, and so should be called to the
2672 attention of support staff. Whatever happened has
2673 probably disrupted the user's work. Examples: an
2674 untagged BAD from an IMAP server.
2677 void mm_log (char *string,long errflg);
2678 string message string
2679 errflg message error level
2681 This function is called to deliver a log message. No newline is
2682 included in the string, so this function has to output its own. In
2683 general, it is intended that these messages are logged someplace, and
2684 possibly shown to the user.
2686 The message error level is one of the following:
2688 NIL normal operation. The text is `babble' that may be
2689 interesting to the user, e.g. "Expunged 3 messages".
2691 PARSE An RFC 822 parsing error. Since bogus headers are
2692 all-too-common in the real world, these can often be
2693 ignored on the "garbage in, garbage out" princple.
2694 However, since surprising results can be yielded when
2695 trying to parse garbage, this message should be logged
2696 somewhere so it can be figured out what happened.
2698 WARN A warning event. This event should be displayed to
2699 the user. It occurs when an error condition has
2700 happened, but c-client knows what to do to recover.
2701 Examples: "Can't open read-write, so opening
2702 read-only", "Empty mailbox", "Login failed, try
2703 again", "Waiting for mailbox to become unlocked",
2704 "IMAP protocol error". Although a user should be
2705 told about a warning, it's generally not necessary
2706 to interrupt the flow of her work (e.g. it's alright
2707 to display the warning in a scrolling window, but
2708 not necessary to require the user to do anything).
2710 ERROR An error event. This event should be displayed to
2711 the user, or at least logged someplace. This is a
2712 serious error condition occured that aborted the
2713 requested operation and possibly also aborted the mail
2714 stream. This ranges from normal error conditions such
2715 as "Can't open mailbox", "too many login failures, go
2716 away" to bizarre conditions such as "Apparent new mail
2717 appeared in the mailbox that doesn't look like mail,
2718 program aborting". Errors must be called to the
2719 user's attention, and probably should require some
2720 sort of acknowledgement (e.g. answering a modal panel)
2721 before the application proceeds.
2724 void mm_dlog (char *string);
2725 string message string
2727 This function is called to deliver a debugging telemetry
2728 message. No newline is included in the string, so this function has
2729 to output its own. This is called only when debugging is enabled.
2732 void mm_login (NETMBX *mb,char *user,char *pwd,long trial);
2733 mb parsed mailbox specification
2734 user pointer to where to return user name
2735 pwd pointer to where to return password
2736 trial number of prior login attempts
2738 This function is called to get a user name and password for the
2739 given network mailbox. It stores the user name and password in the
2740 strings pointed to by the appropriate arguments. The trial argument
2741 is the number of attempts to perform the login and is initially zero
2742 (e.g. for a default username and password login functionality). It is
2743 incremented for each subsequent trial until the maximum number of
2744 trials are made.
2747 void mm_critical (MAILSTREAM *stream);
2748 stream stream where event happened
2750 This function is called to alert the application that c-client
2751 is about to run some critical code on that stream that may result in a
2752 clobbered mail file if it is interrupted. It may be desirable to
2753 disable CTRL/C, etc. during this time.
2756 void mm_nocritical (MAILSTREAM *stream);
2757 stream stream where event happened
2759 This function is called to alert the application that c-client
2760 is no longer running critical code on that stream that may result in a
2761 clobbered mail file if it is interrupted.
2764 long mm_diskerror (MAILSTREAM *stream,long errcode,long serious);
2765 stream stream where event happened
2766 errcode OS error code for disk error
2767 serious non-zero if c-client can not undo the operation (and
2768 thus must retry to avoid mail file damage)
2770 This function is called to alert the application that the
2771 c-client has encountered an unrecoverable write error when trying to
2772 update the mail file. errcode contains the system error code. If
2773 serious is non-zero, then it is probable that the disk copy of the
2774 mailbox has been damaged.
2776 The return value from this function is the abort flag; if serious
2777 is zero and the abort flag is non-zero, the operation is aborted. If
2778 the abort flag is zero or if serious was non-zero, a return from this
2779 function will retry the failing operation.
2782 void mm_fatal (char *string);
2783 string message string
2785 This function is called from the fatal() routine in the
2786 operating system code to notify the main program that it is about to
2787 crash. The string contains a reason. At the very minimum, the main
2788 program should do something like
2789 mm_log (string,ERROR);
2790 and then return. No newline is included in the string, so this
2791 function has to output its own.
2792 \f
2793 Driver interface
2795 When writing a new driver for the c-client, you must provide a
2796 DRIVER stucture giving a dispatch vector between MAIL and the driver.
2797 The DRIVER dispatch vector is described in mail.h.
2799 char *name;
2800 Name by which the driver is known to c-client.
2802 unsigned long flags;
2803 Attribute flags for this driver:
2804 DR_DISABLE This driver is currently disabled.
2805 DR_LOCAL This driver deals with local mailboxes; if
2806 this is off it deals with mailboxes over a
2807 network.
2808 DR_MAIL This driver supports e-mail messages.
2809 DR_NEWS This driver supports netnews messages
2810 DR_READONLY This driver only allows read-only access;
2811 mail_setflag(), mail_expunge(), etc. are
2812 no-ops.
2813 DR_NOFAST This driver does not implement mail_fetchfast()
2814 in a fast way (e.g. it may have to fetch the
2815 entire message text over a network to
2816 calculate sizes).
2817 DR_NAMESPACE This driver accepts and uses namespace format
2818 names.
2819 DR_LOWMEM This driver is designed for systems with very
2820 limited amounts of memory (e.g. DOS) and
2821 support routines called by this driver should
2822 try not to use much memory.
2824 DRIVER *next;
2825 Pointer to the next driver which this application supports (or NIL if
2826 this is the last driver). Drivers are lunk together via the mail_link()
2827 function.
2829 DRIVER *driver_valid (char *mailbox);
2830 This function returns a pointer to the driver's DRIVER dispatch
2831 vector iff this driver accepts the given name as a valid mailbox for this
2832 driver. Otherwise, it returns the value of the next driver's
2833 driver_valid() or NIL if there is no next driver. In other words, calling
2834 driver_valid() for the first driver will return the driver dispatch vector
2835 for the driver which supports this type of mailbox.
2837 void *driver_parameters (long function,void *value);
2838 This function implements mail_parameters() for this driver.
2840 void driver_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents);
2841 This function implements mail_scan() for this driver.
2843 void driver_list (MAILSTREAM *stream,char *ref,char *pat);
2844 This function implements mail_list() for this driver.
2846 void driver_lsub (MAILSTREAM *stream,char *ref,char *pat);
2847 This function implements mail_lsub() for this driver.
2849 long driver_subscribe (MAILSTREAM *stream,char *mailbox);
2850 This function implements mail_subscribe() for this driver.
2852 long driver_unsubscribe (MAILSTREAM *stream,char *mailbox);
2853 This function implements mail_unsubscribe() for this driver.
2855 long driver_create (MAILSTREAM *stream,char *mailbox);
2856 This function implements mail_create() for this driver.
2858 long driver_delete (MAILSTREAM *stream,char *mailbox);
2859 This function implements mail_delete() for this driver.
2861 long driver_rename (MAILSTREAM *stream,char *old,char *new);
2862 This function implements mail_rename() for this driver.
2864 long driver_status (MAILSTREAM *stream,char *mailbox,long flags);
2865 This function implements mail_status() for this driver.
2867 MAILSTREAM *driver_open (MAILSTREAM *stream);
2868 This function opens the mailbox identified by the given stream. It
2869 may use the data on the stream and create additional data on stream->local
2870 as necessary. It should return the given stream unless it failed to open
2871 the mailbox, in which case it should return NIL.
2873 void driver_close (MAILSTREAM *stream,long options);
2874 This function implements mail_close() for this driver.
2876 void driver_fetchfast (MAILSTREAM *stream,char *sequence,long flags);
2877 This function implements mail_fetchfast() for this driver.
2879 void driver_fetchflags (MAILSTREAM *stream,char *sequence,long flags);
2880 This function implements mail_fetchflags() for this driver.
2882 ENVELOPE *driver_fetchstructure (MAILSTREAM *stream,unsigned long msgno,
2883 BODY **body,long flags);
2884 This function implements mail_fetchstructure() for this driver.
2886 char *driver_fetchheader (MAILSTREAM *stream,unsigned long msgno,
2887 STRINGLIST *lines,unsigned long *len,long flags);
2888 This function implements mail_fetchheader() for this driver.
2890 char *driver_fetchtext (MAILSTREAM *stream,unsigned long msgno,
2891 unsigned long *len,long flags);
2892 This function implements mail_fetchtext() for this driver.
2894 char *driver_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *section,
2895 unsigned long *len,long flags);
2896 This function implements mail_fetchbody() for this driver.
2898 void driver_setflag (MAILSTREAM *stream,char *sequence,char *flag,long flags);
2899 This function implements mail_setflag() for this driver.
2901 void driver_clearflag (MAILSTREAM *stream,char *sequence,char *flag,
2902 long flags);
2903 This function implements mail_clearflag() for this driver.
2905 void driver_search (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm,
2906 long flags);
2907 This function implements mail_search() for this driver.
2909 unsigned long *driver_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg,
2910 SORTPGM *pgm,long flags);
2911 This function implements mail_sort() for this driver.
2913 void *driver_thread (MAILSTREAM *stream,char *seq,long function,long flag);
2914 This dispatch is reserved for a future threading capability.
2916 long driver_ping (MAILSTREAM *stream);
2917 This function implements mail_ping() for this driver.
2919 void driver_check (MAILSTREAM *stream);
2920 This function implements mail_check() for this driver.
2922 void driver_expunge (MAILSTREAM *stream);
2923 This function implements mail_expunge() for this driver.
2925 long driver_copy (MAILSTREAM *stream,char *sequence,char *mailbox,
2926 long options);
2927 This function implements mail_copy() for this driver.
2929 long driver_append (MAILSTREAM *stream,char *mailbox,char *flags,char *date,
2930 STRING *message);
2931 This function implements mail_append() for this driver.
2933 void driver_gc (MAILSTREAM *stream,long gcflags);
2934 This function implements mail_gc() for this driver.
2935 \f
2936 Driver Support Functions
2938 void mail_searched (MAILSTREAM *stream,unsigned long msgno);
2939 stream stream where event happened
2940 msgno message number
2942 This function is called by the driver to notify c-client that this
2943 message number matches a search. It invokes the main program's
2944 mm_searched() function.
2946 void mail_exists (MAILSTREAM *stream,unsigned long nmsgs);
2947 stream stream where event happened
2948 nmsgs number of messages
2950 This function is called by the driver to notify c-client that this
2951 message number exists (i.e. there are this many messages in the mailbox).
2952 It invokes the main program's mm_exists() function.
2954 void mail_recent (MAILSTREAM *stream,unsigned long recent);
2955 stream stream where event happened
2956 recent number of messages
2958 This function is called by the driver to notify c-client that this
2959 many messages are "recent" (i.e. arrived in the mailbox since the previous
2960 time the mailbox was opened).
2962 void mail_expunged (MAILSTREAM *stream,unsigned long msgno);
2963 stream stream where event happened
2964 msgno number of messages
2966 This function is called by the driver to notify MAIL that this
2967 message number has been expunged from the mail file and that all subsequent
2968 messages are now referenced by a message number one less than before. It
2969 invokes the main program's mm_expunged() function.
2971 void mail_lock (MAILSTREAM *stream);
2972 stream stream where event happened
2973 This function sets the stream lock. It is an error to set the stream
2974 lock if the stream is already locked.
2976 This is mainly used to catch errors due to a callback function
2977 (e.g. mm_exists) inadvertantly recursing back to the MAIL routines and
2978 establishing an infinite recursion. Normally, drivers will set the lock
2979 prior to calling one of the callback functions above or, more likely, in
2980 the beginning of the driver's non-reentrant "do operation" section. In the
2981 IMAP4 driver, the stream lock is set when entering imap_send() and cleared
2982 on exit.
2984 void mail_unlock (MAILSTREAM *stream);
2985 stream stream where event happened
2987 This function releases the stream lock. It is an error to release the
2988 stream lock if the stream is not locked.