c-client Structures c-client has a large number of structures which are used for multiple functions. The most important of these are described here. The MAILSTREAM structure is used to reference open mailboxes. Applications may reference the following: char *mailbox; mailbox name unsigned short use; stream use count, this is incremented unsigned short sequence; stream sequence, this is incremented each time a stream is reused (i.e. mail_open() is called to open a different mailbox on this stream) unsigned int rdonly : 1; stream is open read-only unsigned int anonymous : 1; stream is open with anonymous access unsigned int halfopen : 1; stream is half-open; it can be reopened or used for functions that don't need a open mailbox such as mail_create() but no message data can be fetched unsigned int perm_seen : 1; Seen flag can be set permanently unsigned int perm_deleted : 1; Deleted flag can be set permanently unsigned int perm_flagged : 1; Flagged flag can be set permanently unsigned int perm_answered :1; Answered flag can be set permanently unsigned int perm_draft : 1; Draft flag can be set permanently unsigned int kwd_create : 1; new user flags can be created by referencing then in mail_setflag() or mail_clearflag(). Note: this can change during a session (e.g. if there is a limit on the number of keywords), so check after creating a new flag to see if any more can be created before letting the user try to do so unsigned long perm_user_flags; corresponding user flags can be set permanently. This is a bit mask which matches the entries in stream->user_flags[] unsigned long gensym; generated unique value. Always referenced with stream->gensys++ unsigned long nmsgs; number of messages in current mailbox unsigned long recent; number of recent messages in current mailbox unsigned long uid_validity; UID validity value; this is used to verify that recorded UIDs match the UIDs that the stream has. If the mailbox does not have matching UIDs (e.g. the UIDs were lost or not recorded) then the UID validity value will be different unsigned long uid_last; highest currently assigned UID in the current mailbox; a new UID will be assigned with ++stream->uid_last char *user_flags[NUSERFLAGS]; pointers to user flag names in bit order from stream->perm_user_flags or elt->user_flags The following MAILSTREAM values are only used internally: DRIVER *dtb; dispatch table for this driver void *local; pointer to driver local data unsigned int lock : 1; stream lock flag (an operation is in progress; used as a bug trap to detect recursion back to c-client from callback routines). unsigned int debug : 1; debugging information should be logged via mm_dlog(). unsigned int silent : 1; don't do main program callbacks on this stream (used when a stream is opened internally) unsigned int scache : 1; short caching; don't cache information in memory The following MAILSTREAM values are only used by the cache manager routine (see the documentation about mailcache_t above): unsigned long cachesize; size of c-client message cache union { void **c; to get at the cache in general MESSAGECACHE **s; message cache array LONGCACHE **l; long cache array } cache; The following MAILSTREAM values are for the convenience of drivers that use short caching and want to be able to garbage collect any values that they returned: unsigned long msgno; message number of `current' message ENVELOPE *env; pointer to `current' message envelope BODY *body; pointer to `current' message body char *text; pointer to `current' text The MESSAGECACHE structure (commonly called an "elt" as a nickname for "cache ELemenT") contains information about messages. Applications may use the following: unsigned long msgno; message number. If the elt is locked (by elt->lockcount++), then the elt pointer can be stored (e.g. with the data for a window which draws this message) and elt->msgno will change automatically whenever expunges are done so the window will always view the correct message. If elt->msgno becomes 0, then the message has been expunged, but the elt won't be freed until the elt lock count is decremented (by mail_free_elt()). unsigned long uid; message unique ID unsigned int hours: 5; internal date hours (0-23) unsigned int minutes: 6; internal date minutes (0-59) unsigned int seconds: 6; internal date seconds (0-59) unsigned int zoccident : 1; non-zero if internal date time zone is west of UTC unsigned int zhours : 4; internal date time zone hours from UTC (0-12) unsigned int zminutes: 6; internal date time zone minutes (0-59) unsigned int seen : 1; message Seen flag unsigned int deleted : 1; message Deleted flag unsigned int flagged : 1; message Flagged flag unsigned int answered : 1; message Answered glag unsigned int draft : 1; message Draft flag unsigned int valid : 1; flags are valid in this elt; an elt that was newly created but never loaded with flags won't have this set. unsigned int recent : 1; message recent flag unsigned int searched : 1; message matches search criteria in most recent mail_search_full() call unsigned int spare : 1; reserved for application use unsigned int spare2 : 1; reserved for application use unsigned int spare3 : 1; reserved for application use unsigned int lockcount : 8; non-zero if multiple references to this elt. Refer to the msgno member for more information. unsigned int day : 5; internal date day of month (1-31) unsigned int month : 4; internal date month of year (1-12) unsigned int year : 7; internal date year since BASEYEAR (currently 1970; was 1969 in older versions so use BASEYEAR instead of having the base year wired in) unsigned long user_flags; message user flags; this is a bit mask which matches the entries in stream->user_flags[] unsigned long rfc822_size; size of message in octets The following MESSAGECACHE values are only used internally by drivers: unsigned int sequence : 1; message is in sequence from either mail_sequence() or mail_uid_sequence() unsigned long data1; first data item unsigned long data2; second data item unsigned long data3; third data item unsigned long data4; fourth data item The ADDRESS structure is a parsed form of a linked list of RFC 822 addresses. It contains the following information: char *personal; personal name phrase char *adl; at-domain-list (also called "source route") char *mailbox; mailbox name char *host; domain name of mailbox's host char *error; error in address from smtp_mail(); if an error is returned from smtp_mail() for one of the recipient addresses the SMTP server's error text for that recipient can be found here. If it is null then there was no error (or an error was found with a prior recipient ADDRESS *next; pointer to next address in list The ENVELOPE structure is a parsed form of the RFC 822 header. Its member names correspond to the RFC 822 field names. It contains the following information: char *remail; remail header if any ADDRESS *return_path; error return address char *date; message composition date string ADDRESS *from; from address list ADDRESS *sender; sender address list ADDRESS *reply_to; reply address list char *subject; message subject string ADDRESS *to; primary recipient list ADDRESS *cc; secondary recipient list ADDRESS *bcc; blind secondary recipient list char *in_reply_to; replied message ID char *message_id; message ID char *newsgroups; USENET newsgroups char *followup_to; USENET reply newsgroups char *references; USENET references The BODY structure is a parsed form of a linked list of the MIME structure of a message. It contains the following information. unsigned short type; body primary type code. This is an index into the body_types vector of body type names. The following body types are pre-defined: TYPETEXT unformatted text TYPEMULTIPART multiple part TYPEMESSAGE encapsulated message TYPEAPPLICATION application data TYPEAUDIO audio TYPEIMAGE static image (GIF, JPEG, etc.) TYPEVIDEO video TYPEOTHER unknown Additional types up to TYPEMAX are dynamically defined if they are encountered by c-client. unsigned short encoding; body transfer encoding. This is an index into the body_encodings vector of body encoding names. The following body encodings are pre-defined: ENC7BIT 7 bit SMTP semantic data ENC8BIT 8 bit SMTP semantic data ENCBINARY 8 bit binary data ENCBASE64 base-64 encoded data ENCQUOTEDPRINTABLE human-readable 8-as-7 bit data ENCOTHER unknown Additional encodings up to ENCMAX are dynamically defined if they are encountered by c-client. char *subtype; body subtype string PARAMETER *parameter; parameter list char *id; body content identifier char *description; body content description unsigned char *contents.text; when composing a message that is NOT of TYPEMULTIPART, non-binary text of the content is stored here. Note that this happens even when the text is of TYPEMESSAGE. Text of encoding ENC8BIT may be converted to ENCQUOTEDPRINTABLE when it is sent. This should not be referenced for any other reason; in particular, this is NOT the way for an application to access content data (use mail_fetchbody_full() instead). BINARY *contents.binary; when composing a message that is NOT of TYPEMULTIPART, binary content (of encoding ENCBINARY) is stored here. It will be converted to ENCBASE64 when it is sent. This should not be referenced for any other reason; in particular, this is NOT the way for an application to access content data (use mail_fetchbody_full() instead). PART *contents.part; for body parts of TYPEMULTIPART, this contains the list of body parts in this multipart MESSAGE contents.msg; for body parts of TYPEMESSAGE with subtype "RFC822", this contains the encapsulated message unsigned long size.lines; size in lines unsigned long size.bytes; size in octets. This MUST be set when composing a message if the encoding is ENC8BIT or ENCBINARY. char *md5; body content MD5 checksum The following BODY information is used only by c-client internally. The use of this data is driver-specific and it can not be relied-upon by applications. unsigned char *contents.text; drivers can store a pointer to the body contents as text here. unsigned long size.ibytes; internal size of the body content (prior to newline conversion, etc.) in octets The MESSAGE structure is a parsed form of a MESSAGE/RFC822 MIME body part. It contains the following information: ENVELOPE *env; encapsulated message RFC 822 header BODY *body; encapsulated message MIME structure The following MESSAGE information is used only by c-client internally. The use of this data is driver-specific and it can not be relied-upon by applications. char *hdr; encapsulated message header unsigned long hdrsize; message header size char *text; message in RFC 822 form unsigned long offset; offset of text from header The PARAMETER structure is a parsed form of a linked list of attribute/value pairs. It contains the following information: char *attribute; attribute name char *value; value PARAMETER *next; next parameter in list The PART structure is a parsed form of a linked list of MIME body parts. It contains the following information: BODY body; body information for this part PART *next; next body part The following PART information is used only by c-client internally. The use of this data is driver-specific and it can not be relied-upon by applications. unsigned long offset; offset from body origin The NETMBX structure is a parsed form of a network mailbox name: char host[NETMAXHOST]; remote host name char user[NETMAXUSER]; remote user name if specified char mailbox[NETMAXMBX]; remote mailbox name char service[NETMAXSRV]; remote service name (IMAP4, NNTP, etc.) unsigned long port; TCP/IP port number if specified unsigned int anoflag : 1; anonymous access requested unsigned int dbgflag : 1; protocol debugging telemetry, via mm_dlog(), requested The STRINGLIST structure is a list of strings (which may have embedded NULs) and their lengths: char *text; string text unsigned long size; string length STRINGLIST *next; next string in list