imapext-2007: docs/internal.txt annotate

imapext-2007

annotate docs/internal.txt @ 0:ada5e610ab86

imap-2007e

author	yuuji@gentei.org
date	Mon, 14 Sep 2009 15:17:45 +0900
parents
children

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