Diffstat (limited to 'libetpan/include/libetpan/mailimap.h') (more/less context) (ignore whitespace changes)
| -rw-r--r-- | libetpan/include/libetpan/mailimap.h | 598 |
1 files changed, 598 insertions, 0 deletions
diff --git a/libetpan/include/libetpan/mailimap.h b/libetpan/include/libetpan/mailimap.h new file mode 100644 index 0000000..e31e2d2 --- a/dev/null +++ b/libetpan/include/libetpan/mailimap.h @@ -0,0 +1,598 @@ +/* + * libEtPan! -- a mail stuff library + * + * Copyright (C) 2001, 2005 - DINH Viet Hoa + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the libEtPan! project nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +/* + * $Id$ + */ + +#ifndef MAILIMAP_H + +#define MAILIMAP_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include <libetpan/mailimap_types.h> +#include <libetpan/mailimap_types_helper.h> +#include <libetpan/mailimap_helper.h> + +#include <libetpan/mailimap_socket.h> +#include <libetpan/mailimap_ssl.h> + +/* + mailimap_connect() + + This function will connect the IMAP session with the given stream. + + @param session the IMAP session + @param s stream to use + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes + + note that on success, MAILIMAP_NO_ERROR_AUTHENTICATED or + MAILIMAP_NO_ERROR_NON_AUTHENTICATED is returned + + MAILIMAP_NO_ERROR_NON_AUTHENTICATED is returned when you need to + use mailimap_login() to authenticate, else + MAILIMAP_NO_ERROR_AUTHENTICATED is returned. +*/ + +int mailimap_connect(mailimap * session, mailstream * s); + +/* + mailimap_append() + + This function will append a given message to the given mailbox + by sending an APPEND command. + + @param session the IMAP session + @param mailbox name of the mailbox + @param flag_list flags of the message + @param date_time timestamp of the message + @param literal content of the message + @param literal_size size of the message + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_append(mailimap * session, const char * mailbox, + struct mailimap_flag_list * flag_list, + struct mailimap_date_time * date_time, + const char * literal, size_t literal_size); + +/* + mailimap_noop() + + This function will poll for an event on the server by + sending a NOOP command to the IMAP server + + @param session IMAP session + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR_XXX codes +*/ + +int mailimap_noop(mailimap * session); + +/* + mailimap_logout() + + This function will logout from an IMAP server by sending + a LOGOUT command. + + @param session IMAP session + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_logout(mailimap * session); + +/* + mailimap_capability() + + This function will query an IMAP server for his capabilities + by sending a CAPABILITY command. + + @param session IMAP session + @param result The result of this command is a list of + capabilities and it is stored into (* result). + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes + */ + +int mailimap_capability(mailimap * session, + struct mailimap_capability_data ** result); + +/* + mailimap_check() + + This function will request for a checkpoint of the mailbox by + sending a CHECK command. + + @param session IMAP session + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes + */ + +int mailimap_check(mailimap * session); + +/* + mailimap_close() + + This function will close the selected mailbox by sending + a CLOSE command. + + @param session IMAP session + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes + */ + +int mailimap_close(mailimap * session); + +/* + mailimap_expunge() + + This function will permanently remove from the selected mailbox + message that have the \Deleted flag set. + + @param session IMAP session + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_expunge(mailimap * session); + +/* + mailimap_copy() + + This function will copy the given messages from the selected mailbox + to the given mailbox. + + @param session IMAP session + @param set This is a set of message numbers. + @param mb This is the destination mailbox. + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes + */ + +int mailimap_copy(mailimap * session, struct mailimap_set * set, + const char * mb); + +/* + mailimap_uid_copy() + + This function will copy the given messages from the selected mailbox + to the given mailbox. + + @param session IMAP session + @param set This is a set of message unique identifiers. + @param mb This is the destination mailbox. + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes + */ + +int mailimap_uid_copy(mailimap * session, + struct mailimap_set * set, const char * mb); + +/* + mailimap_create() + + This function will create a mailbox. + + @param session IMAP session + @param mb This is the name of the mailbox to create. + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_create(mailimap * session, const char * mb); + +/* + mailimap_delete() + + This function will delete a mailox. + + @param session IMAP session + @param mb This is the name of the mailbox to delete. + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_delete(mailimap * session, const char * mb); + +/* + mailimap_examine() + + This function will select the mailbox for read-only operations. + + @param session IMAP session + @param mb This is the name of the mailbox to select. + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_examine(mailimap * session, const char * mb); + +/* + mailimap_fetch() + + This function will retrieve data associated with the given message + numbers. + + @param session IMAP session + @param set set of message numbers + @param fetch_type type of information to be retrieved + @param result The result of this command is a clist + and it is stored into (* result). Each element of the clist is a + (struct mailimap_msg_att *). + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_fetch(mailimap * session, struct mailimap_set * set, + struct mailimap_fetch_type * fetch_type, clist ** result); + +/* + mailimap_fetch() + + This function will retrieve data associated with the given message + numbers. + + @param session IMAP session + @param set set of message unique identifiers + @param fetch_type type of information to be retrieved + @param result The result of this command is a clist + and it is stored into (* result). Each element of the clist is a + (struct mailimap_msg_att *). + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_uid_fetch(mailimap * session, + struct mailimap_set * set, + struct mailimap_fetch_type * fetch_type, clist ** result); + +/* + mailimap_fetch_list_free() + + This function will free the result of a fetch command. + + @param fetch_list This is the clist containing + (struct mailimap_msg_att *) elements to free. +*/ + +void mailimap_fetch_list_free(clist * fetch_list); + +/* + mailimap_list() + + This function will return the list of the mailbox + available on the server. + + @param session IMAP session + @param mb This is the reference name that informs + of the level of hierarchy + @param list_mb mailbox name with possible wildcard + @param result This will store a clist of (struct mailimap_mailbox_list *) + in (* result) + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_list(mailimap * session, const char * mb, + const char * list_mb, clist ** result); + +/* + mailimap_login() + + This function will authenticate the client. + + @param session IMAP session + @param userid login of the user + @param password password of the user + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_login(mailimap * session, + const char * userid, const char * password); + +/* + mailimap_lsub() + + This function will return the list of the mailbox + that the client has subscribed to. + + @param session IMAP session + @param mb This is the reference name that informs + of the level of hierarchy + @param list_mb mailbox name with possible wildcard + @param result This will store a list of (struct mailimap_mailbox_list *) + in (* result) + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_lsub(mailimap * session, const char * mb, + const char * list_mb, clist ** result); + +/* + mailimap_list_result_free() + + This function will free the clist of (struct mailimap_mailbox_list *) + + @param list This is the clist to free. +*/ + +void mailimap_list_result_free(clist * list); + +/* + mailimap_rename() + + This function will change the name of a mailbox. + + @param session IMAP session + @param mb current name + @param new_name new name + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_rename(mailimap * session, + const char * mb, const char * new_name); + +/* + mailimap_search() + + All mails that match the given criteria will be returned + their numbers in the result list. + + @param session IMAP session + @param charset This indicates the charset of the strings that appears + in the searching criteria + @param key This is the searching criteria + @param result The result is a clist of (uint32_t *) and will be + stored in (* result). + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_search(mailimap * session, const char * charset, + struct mailimap_search_key * key, clist ** result); + +/* + mailimap_uid_search() + + + All mails that match the given criteria will be returned + their unique identifiers in the result list. + + @param session IMAP session + @param charset This indicates the charset of the strings that appears + in the searching criteria + @param key This is the searching criteria + @param result The result is a clist of (uint32_t *) and will be + stored in (* result). + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_uid_search(mailimap * session, const char * charset, + struct mailimap_search_key * key, clist ** result); + +/* + mailimap_search_result_free() + + This function will free the result of the a search. + + @param search_result This is a clist of (uint32_t *) returned + by mailimap_uid_search() or mailimap_search() +*/ + +void mailimap_search_result_free(clist * search_result); + +/* + mailimap_select() + + This function will select a given mailbox so that messages in the + mailbox can be accessed. + + @param session IMAP session + @param mb This is the name of the mailbox to select. + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_select(mailimap * session, const char * mb); + +/* + mailimap_status() + + This function will return informations about a given mailbox. + + @param session IMAP session + @param mb This is the name of the mailbox + @param status_att_list This is the list of mailbox information to return + @param result List of returned values + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_status(mailimap * session, const char * mb, + struct mailimap_status_att_list * status_att_list, + struct mailimap_mailbox_data_status ** result); + +/* + mailimap_uid_store() + + This function will alter the data associated with some messages + (flags of the messages). + + @param session IMAP session + @param set This is a list of message numbers. + @param store_att_flags This is the data to associate with the + given messages + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_store(mailimap * session, + struct mailimap_set * set, + struct mailimap_store_att_flags * store_att_flags); + +/* + mailimap_uid_store() + + This function will alter the data associated with some messages + (flags of the messages). + + @param session IMAP session + @param set This is a list of message unique identifiers. + @param store_att_flags This is the data to associate with the + given messages + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int +mailimap_uid_store(mailimap * session, + struct mailimap_set * set, + struct mailimap_store_att_flags * store_att_flags); + +/* + mailimap_subscribe() + + This function adds the specified mailbox name to the + server's set of "active" or "subscribed" mailboxes. + + @param session IMAP session + @param mb This is the name of the mailbox + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_subscribe(mailimap * session, const char * mb); + +/* + mailimap_unsubscribe() + + This function removes the specified mailbox name to the + server's set of "active" or "subscribed" mailboxes. + + @param session IMAP session + @param mb This is the name of the mailbox + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR codes +*/ + +int mailimap_unsubscribe(mailimap * session, const char * mb); + +/* + mailimap_starttls() + + This function starts change the mode of the connection to + switch to SSL connection. + + @param session IMAP session + + @return the return code is one of MAILIMAP_ERROR_XXX or + MAILIMAP_NO_ERROR_XXX codes + */ + +int mailimap_starttls(mailimap * session); + +/* + mailimap_new() + + This function returns a new IMAP session. + + @param progr_rate When downloading messages, a function will be called + each time the amount of bytes downloaded reaches a multiple of this + value, this can be 0. + @param progr_fun This is the function to call to notify the progress, + this can be NULL. + + @return an IMAP session is returned. + */ + +mailimap * mailimap_new(size_t imap_progr_rate, + progress_function * imap_progr_fun); + +/* + mailimap_free() + + This function will free the data structures associated with + the IMAP session. + + @param session IMAP session + */ + +void mailimap_free(mailimap * session); + +#ifdef __cplusplus +} +#endif + +#endif |