Menu
▾
▴
[libEtPan-commits] CVS: libetpan/imf mailimf_types.h,1.20,1.21 mailimf_types_helper.h,1.7,1.8 mailimf_write.h,1.6,1.7
|
From: DINH V. H. <ho...@us...> - 2002-11-25 07:09:28
|
Update of /cvsroot/libetpan/libetpan/imf
In directory sc8-pr-cvs1:/tmp/cvs-serv28707/imf
Modified Files:
mailimf_types.h mailimf_types_helper.h mailimf_write.h
Log Message:
comments for higher level API
Index: mailimf_types.h
===================================================================
RCS file: /cvsroot/libetpan/libetpan/imf/mailimf_types.h,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -d -r1.20 -r1.21
--- mailimf_types.h 17 Nov 2002 03:19:26 -0000 1.20
+++ mailimf_types.h 25 Nov 2002 07:09:24 -0000 1.21
@@ -41,9 +41,6 @@
#ifdef __cplusplus
extern "C" {
#endif
-#if 0
-}
-#endif
#include "clist.h"
@@ -408,14 +405,16 @@
+/*
+ mailimf_orig_date is the parsed Date field
+ - date_time is the parsed date
+*/
struct mailimf_orig_date {
struct mailimf_date_time * date_time; /* != NULL */
};
-
-
struct mailimf_orig_date * mailimf_orig_date_new(struct mailimf_date_time *
date_time);
@@ -424,7 +423,11 @@
+/*
+ mailimf_from is the parsed From field
+ - mb_list is the parsed mailbox list
+*/
struct mailimf_from {
struct mailimf_mailbox_list * mb_list; /* != NULL */
@@ -436,7 +439,11 @@
+/*
+ mailimf_sender is the parsed Sender field
+ - mb is the parsed mailbox
+*/
struct mailimf_sender {
struct mailimf_mailbox * mb; /* != NULL */
@@ -449,7 +456,11 @@
+/*
+ mailimf_reply_to is the parsed Reply-To field
+ - addr_list is the parsed address list
+ */
struct mailimf_reply_to {
struct mailimf_address_list * addr_list; /* != NULL */
@@ -463,7 +474,11 @@
-
+/*
+ mailimf_to is the parsed To field
+
+ - addr_list is the parsed address list
+*/
struct mailimf_to {
struct mailimf_address_list * addr_list; /* != NULL */
@@ -476,7 +491,11 @@
+/*
+ mailimf_cc is the parsed Cc field
+ - addr_list is the parsed addres list
+*/
struct mailimf_cc {
struct mailimf_address_list * addr_list; /* != NULL */
@@ -489,6 +508,11 @@
+/*
+ mailimf_bcc is the parsed Bcc field
+
+ - addr_list is the parsed addres list
+*/
struct mailimf_bcc {
struct mailimf_address_list * addr_list; /* can be NULL */
@@ -500,7 +524,11 @@
-
+/*
+ mailimf_message_id is the parsed Message-ID field
+
+ - value is the message identifier
+*/
struct mailimf_message_id {
char * value; /* != NULL */
@@ -513,9 +541,15 @@
+/*
+ mailimf_in_reply_to is the parsed In-Reply-To field
+
+ - msg_id_list is the list of message identifers
+*/
struct mailimf_in_reply_to {
- clist * msg_id_list; /* != NULL */
+ clist * msg_id_list; /* list of (char *) */
+ /* != NULL */
};
struct mailimf_in_reply_to * mailimf_in_reply_to_new(clist * msg_id_list);
@@ -524,8 +558,15 @@
+/*
+ mailimf_references is the parsed References field
+
+ - msg_id_list is the list of message identifiers
+ */
+
struct mailimf_references {
- clist * msg_id_list; /* != NULL */
+ clist * msg_id_list; /* list of (char *) */
+ /* != NULL */
};
struct mailimf_references * mailimf_references_new(clist * msg_id_list);
@@ -534,6 +575,11 @@
+/*
+ mailimf_subject is the parsed Subject field
+
+ - value is the value of the field
+*/
struct mailimf_subject {
char * value; /* != NULL */
@@ -544,6 +590,12 @@
void mailimf_subject_free(struct mailimf_subject * subject);
+/*
+ mailimf_comments is the parsed Comments field
+
+ - value is the value of the field
+*/
+
struct mailimf_comments {
char * value; /* != NULL */
};
@@ -553,8 +605,15 @@
void mailimf_comments_free(struct mailimf_comments * comments);
+/*
+ mailimf_keywords is the parsed Keywords field
+
+ - list is the list of keywords
+*/
+
struct mailimf_keywords {
- clist * list; /* != NULL */
+ clist * list; /* list of (char *) */
+ /* != NULL */
};
struct mailimf_keywords * mailimf_keywords_new(clist * list);
@@ -562,6 +621,12 @@
void mailimf_keywords_free(struct mailimf_keywords * keywords);
+/*
+ mailimf_return is the parsed Return-Path field
+
+ - path is the parsed value of Return-Path
+*/
+
struct mailimf_return {
struct mailimf_path * path; /* != NULL */
};
@@ -572,6 +637,11 @@
void mailimf_return_free(struct mailimf_return * return_path);
+/*
+ mailimf_path is the parsed value of Return-Path
+
+ - addr_spec is a mailbox
+*/
struct mailimf_path {
char * addr_spec; /* can be NULL */
@@ -582,6 +652,14 @@
void mailimf_path_free(struct mailimf_path * path);
+/*
+ mailimf_optional_field is a non-parsed field
+
+ - name is the name of the field
+
+ - value is the value of the field
+*/
+
struct mailimf_optional_field {
char * name; /* != NULL */
char * value; /* != NULL */
@@ -592,6 +670,40 @@
void mailimf_optional_field_free(struct mailimf_optional_field * opt_field);
+
+/*
+ mailimf_fields is the native structure that IMF module will use,
+ this module will provide an easier structure to use when parsing fields.
+
+ mailimf_single_fields is an easier structure to get parsed fields,
+ rather than iteration over the list of fields
+
+ - orig_date is the parsed "Date" field
+
+ - from is the parsed "From" field
+
+ - sender is the parsed "Sender "field
+
+ - reply_to is the parsed "Reply-To" field
+
+ - to is the parsed "To" field
+
+ - cc is the parsed "Cc" field
+
+ - bcc is the parsed "Bcc" field
+
+ - message_id is the parsed "Message-ID" field
+
+ - in_reply_to is the parsed "In-Reply-To" field
+
+ - references is the parsed "References" field
+
+ - subject is the parsed "Subject" field
+
+ - comments is the parsed "Comments" field
+
+ - keywords is the parsed "Keywords" field
+*/
struct mailimf_single_fields {
struct mailimf_orig_date * orig_date; /* can be NULL */
Index: mailimf_types_helper.h
===================================================================
RCS file: /cvsroot/libetpan/libetpan/imf/mailimf_types_helper.h,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- mailimf_types_helper.h 17 Nov 2002 03:19:26 -0000 1.7
+++ mailimf_types_helper.h 25 Nov 2002 07:09:25 -0000 1.8
@@ -39,30 +39,122 @@
#include "mailimf_types.h"
+/*
+ IMPORTANT NOTE:
+
+ All allocation functions will take as argument allocated data
+ and will store these data in the structure they will allocate.
+ Data should be persistant during all the use of the structure
+ and will be freed by the free function of the structure
+
+ allocation functions will return NULL on failure
+*/
+
+/*
+ mailimf_mailbox_list_new_empty creates an empty list of mailboxes
+*/
+
struct mailimf_mailbox_list *
mailimf_mailbox_list_new_empty();
+/*
+ mailimf_mailbox_list_add adds a mailbox to the list of mailboxes
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_mailbox_list_add(struct mailimf_mailbox_list * mailbox_list,
struct mailimf_mailbox * mb);
+/*
+ mailimf_mailbox_list_add_parse parse the given string
+ into a mailimf_mailbox structure and adds it to the list of mailboxes
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_mailbox_list_add_parse(struct mailimf_mailbox_list * mailbox_list,
char * mb_str);
+/*
+ mailimf_mailbox creates a mailimf_mailbox structure with the given
+ arguments and adds it to the list of mailboxes
+
+ - display_name is the name that will be displayed for this mailbox,
+ for example 'name' in '"name" <mailbox@domain>,
+ should be allocated with malloc()
+
+ - address is the mailbox, for example 'mailbox@domain'
+ in '"name" <mailbox@domain>, should be allocated with malloc()
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_mailbox_list_add_mb(struct mailimf_mailbox_list * mailbox_list,
char * display_name, char * address);
+/*
+ mailimf_address_list_new_empty creates an empty list of addresses
+*/
+
struct mailimf_address_list *
mailimf_address_list_new_empty();
+/*
+ mailimf_address_list_add adds a mailbox to the list of addresses
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_address_list_add(struct mailimf_address_list * address_list,
struct mailimf_address * addr);
+/*
+ mailimf_address_list_add_parse parse the given string
+ into a mailimf_address structure and adds it to the list of addresses
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_address_list_add_parse(struct mailimf_address_list * address_list,
char * addr_str);
+/*
+ mailimf_address_list_add_mb creates a mailbox mailimf_address
+ with the given arguments and adds it to the list of addresses
+
+ - display_name is the name that will be displayed for this mailbox,
+ for example 'name' in '"name" <mailbox@domain>,
+ should be allocated with malloc()
+
+ - address is the mailbox, for example 'mailbox@domain'
+ in '"name" <mailbox@domain>, should be allocated with malloc()
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_address_list_add_mb(struct mailimf_address_list * address_list,
char * display_name, char * address);
+/*
+ mailimf_resent_fields_add_data adds a set of resent fields in the
+ given mailimf_fields structure.
+
+ if you don't want a given field in the set to be added in the list
+ of fields, you can give NULL as argument
+
+ @param resent_msg_id sould be allocated with malloc()
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int
mailimf_resent_fields_add_data(struct mailimf_fields * fields,
struct mailimf_date_time * resent_date,
@@ -73,6 +165,19 @@
struct mailimf_address_list * resent_bcc,
char * resent_msg_id);
+/*
+ mailimf_resent_fields_new_with_data_all creates a new mailimf_fields
+ structure with a set of resent fields
+
+ if you don't want a given field in the set to be added in the list
+ of fields, you can give NULL as argument
+
+ @param resent_msg_id sould be allocated with malloc()
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
struct mailimf_fields *
mailimf_resent_fields_new_with_data_all(struct mailimf_date_time *
resent_date, struct mailimf_mailbox_list * resent_from,
@@ -82,6 +187,18 @@
struct mailimf_address_list * resent_bcc,
char * resent_msg_id);
+/*
+ mailimf_resent_fields_new_with_data_all creates a new mailimf_fields
+ structure with a set of resent fields.
+ Resent-Date and Resent-Message-ID fields will be generated for you.
+
+ if you don't want a given field in the set to be added in the list
+ of fields, you can give NULL as argument
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
struct mailimf_fields *
mailimf_resent_fields_new_with_data(struct mailimf_mailbox_list * from,
struct mailimf_mailbox * sender,
@@ -89,12 +206,43 @@
struct mailimf_address_list * cc,
struct mailimf_address_list * bcc);
+/*
+ this function creates a new mailimf_fields structure with no fields
+*/
+
struct mailimf_fields *
mailimf_fields_new_empty(void);
+
+/*
+ this function adds a field to the mailimf_fields structure
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_fields_add(struct mailimf_fields * fields,
struct mailimf_field * field);
+
+/*
+ mailimf_fields_add_data adds a set of fields in the
+ given mailimf_fields structure.
+
+ if you don't want a given field in the set to be added in the list
+ of fields, you can give NULL as argument
+
+ @param msg_id sould be allocated with malloc()
+ @param subject should be allocated with malloc()
+ @param in_reply_to each elements of this list should be allocated
+ with malloc()
+ @param references each elements of this list should be allocated
+ with malloc()
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
int mailimf_fields_add_data(struct mailimf_fields * fields,
struct mailimf_date_time * date,
struct mailimf_mailbox_list * from,
@@ -108,6 +256,24 @@
clist * references,
char * subject);
+/*
+ mailimf_fields_new_with_data_all creates a new mailimf_fields
+ structure with a set of fields
+
+ if you don't want a given field in the set to be added in the list
+ of fields, you can give NULL as argument
+
+ @param message_id sould be allocated with malloc()
+ @param subject should be allocated with malloc()
+ @param in_reply_to each elements of this list should be allocated
+ with malloc()
+ @param references each elements of this list should be allocated
+ with malloc()
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
struct mailimf_fields *
mailimf_fields_new_with_data_all(struct mailimf_date_time * date,
struct mailimf_mailbox_list * from,
@@ -121,6 +287,24 @@
clist * references,
char * subject);
+/*
+ mailimf_fields_new_with_data creates a new mailimf_fields
+ structure with a set of fields
+ Date and Message-ID fields will be generated for you.
+
+ if you don't want a given field in the set to be added in the list
+ of fields, you can give NULL as argument
+
+ @param subject should be allocated with malloc()
+ @param in_reply_to each elements of this list should be allocated
+ with malloc()
+ @param references each elements of this list should be allocated
+ with malloc()
+
+ @return MAILIMF_NO_ERROR will be returned on success,
+ other code will be returned otherwise
+*/
+
struct mailimf_fields *
mailimf_fields_new_with_data(struct mailimf_mailbox_list * from,
struct mailimf_mailbox * sender,
@@ -132,19 +316,46 @@
clist * references,
char * subject);
+/*
+ this function returns an allocated message identifier to
+ use in a Message-ID or Resent-Message-ID field
+*/
+
char * mailimf_get_message_id();
+/*
+ this function returns a mailimf_date_time structure to
+ use in a Date or Resent-Date field
+*/
+
struct mailimf_date_time * mailimf_get_current_date();
+/*
+ mailimf_single_fields_init fills a mailimf_single_fields structure
+ with the content of a mailimf_fields structure
+*/
+
void mailimf_single_fields_init(struct mailimf_single_fields * single_fields,
struct mailimf_fields * fields);
+/*
+ mailimf_single_fields_new creates a new mailimf_single_fields and
+ fills the structure with mailimf_fields
+*/
+
struct mailimf_single_fields *
mailimf_single_fields_new(struct mailimf_fields * fields);
void mailimf_single_fields_free(struct mailimf_single_fields *
single_fields);
+
+/*
+ mailimf_field_new_custom creates a new field of type optional
+
+ @param name should be allocated with malloc()
+ @param value should be allocated with malloc()
+*/
struct mailimf_field * mailimf_field_new_custom(char * name, char * value);
Index: mailimf_write.h
===================================================================
RCS file: /cvsroot/libetpan/libetpan/imf/mailimf_write.h,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- mailimf_write.h 17 Nov 2002 03:19:26 -0000 1.6
+++ mailimf_write.h 25 Nov 2002 07:09:25 -0000 1.7
@@ -40,16 +40,66 @@
#include <stdio.h>
#include "mailimf_types.h"
+/*
+ mailimf_string_write writes a string to a given stream
+
+ @param f is the stream
+ @param col (* col) is the column number where we will start to
+ write the text, the ending column will be stored in (* col)
+ @param str is the string to write
+*/
+
int mailimf_string_write(FILE * f, int * col,
char * str, size_t length);
+
+
+/*
+ mailimf_fields_write writes the fields to a given stream
+
+ @param f is the stream
+ @param col (* col) is the column number where we will start to
+ write the text, the ending column will be stored in (* col)
+ @param fields is the fields to write
+*/
+
int mailimf_fields_write(FILE * f, int * col,
struct mailimf_fields * fields);
+
+/*
+ mailimf_envelope_fields_write writes only some fields to a given stream
+
+ @param f is the stream
+ @param col (* col) is the column number where we will start to
+ write the text, the ending column will be stored in (* col)
+ @param fields is the fields to write
+*/
+
int mailimf_envelope_fields_write(FILE * f, int * col,
struct mailimf_fields * fields);
+
+/*
+ mailimf_field_write writes a field to a given stream
+
+ @param f is the stream
+ @param col (* col) is the column number where we will start to
+ write the text, the ending column will be stored in (* col)
+ @param field is the field to write
+*/
+
int mailimf_field_write(FILE * f, int * col,
struct mailimf_field * field);
+
+/*
+ mailimf_quoted_string_write writes a string that is quoted
+ to a given stream
+
+ @param f is the stream
+ @param col (* col) is the column number where we will start to
+ write the text, the ending column will be stored in (* col)
+ @param string is the string to quote and write
+*/
int mailimf_quoted_string_write(FILE * f, int * col,
char * string, size_t len);
|