libspopc.h

Go to the documentation of this file.
00001 /* this is libspopc.h file.
00002  * this is part of the libspopc library sources
00003  * copyright  2002 Benoit Rouits <brouits@free.fr>
00004  * released under the terms of GNU LGPL
00005  * (GNU Lesser General Public Licence).
00006  * libspopc offers simple API for a pop3 client (MDA).
00007  * See RFC 1725 for pop3 specifications.
00008  * more information on http://brouits.free.fr/libspopc/
00009  */
00010 #ifndef LIBSPOPC_H
00011 #define LIBSPOPC_H
00012 #ifdef __cplusplus
00013 extern "C" {
00014 #endif
00015 #include <sys/types.h>
00016 #ifdef _MSC_VER
00017 #include <winsock.h>
00018 #else
00019 #include <sys/socket.h>
00020 #include <netinet/in.h>
00021 #include <netdb.h>
00022 #endif
00023 
00024 /***************************************
00025  * low-level methods for a pop3 client *
00026  ***************************************/
00027 #define SOCKET_TIMEOUT 15
00028 #define TCPBUFLEN 512
00029 /******************************************************************************
00030  * Be careful, using the low-level API is uncompliant with using the high     *
00031  * level API. Here, you make your choice. If you don't know the pop3 protocol *
00032  * or what a socket is, it is then warmly recommended to use the *high-level* *
00033  * API if which is shown far below on this file.                              *
00034  ******************************************************************************/
00035 
00036 /**************
00037  * connecting *
00038  **************/
00039 
00040 int pop3_prepare(const char* servername, const int port, struct sockaddr_in* connection, struct hostent* server);
00041 /* prepares the pop session and returns a socket descriptor */
00042 
00043 char* pop3_connect(int sock, struct sockaddr_in* connection);
00044 /* connects to the server through the sock and returns server's welcome */
00045 
00046 void pop3_disconnect(int sock);
00047 /* close socket  */
00048 
00049 
00050 /****************
00051  * pop3 queries *
00052  ****************/
00053 
00054 char* pop3_user(int sock, const char* name);
00055 /* performs "USER" pop query and returns server's <512 bytes response */
00056 
00057 char* pop3_pass(int sock, const char* pw);
00058 /* performs "PASS" pop query and return server's <512 bytes response */
00059 
00060 char* pop3_quit(int sock);
00061 /* performs "QUIT" pop query and returns server's <512 bytes response */
00062 
00063 char* pop3_stat(int sock);
00064 /* performs "STAT" pop query and returns server's <512 bytes response */
00065 
00066 
00067 char* pop3_list(int sock, int id);
00068 /* performs a "LIST" pop query and returns server's (long) response */
00069 
00070 char* pop3_retr(int sock, int id);
00071 /* performs a "RETR" pop query and returns server's (long) response */
00072 
00073 char* pop3_dele(int sock, int id);
00074 /* performs a "DELE" pop query and returns server's <512 bytes response */
00075 
00076 char* pop3_noop(int sock);
00077 /* performs a "NOOP" pop query and returns server's <512 bytes response */
00078 
00079 char* pop3_rset(int sock);
00080 /* performs a "RSET" pop query and returns server's <512 bytes response */
00081 
00082 char* pop3_top(int sock, int id, int lines);
00083 /* performs a "TOP" pop query and returns server's (long) response */
00084 
00085 char* pop3_uidl(int sock, int id);
00086 /* performs a "UIDL" pop query and returns server's (long) response */
00087 
00088 char* pop3_apop(int sock, const char* name, const char* digest);
00089 /* performs a "APOP" secure pop query and returns server's <512 bytes response */
00090 
00091 /* this one is not in the API, just for libspopc internal use: */
00092 char* recv_rest(int sock, char* buf, int cs, int bs);
00093 /* recv rest of data through sock, given a cs bytes filled buffer of total size bs */
00094 /* end of data is assumed when data has a "\n.\n" or "\n.\0" string */
00095 
00096 /*********************
00097  * parsing utilities *
00098  *********************/
00099 #define DOTBEGIN(s) ((s)[0]=='\n'&&(s)[1]=='.')
00100 
00101 int dotline(char* buf);
00102 /* returns 1 if buf contains a "\n.\n" or "\n.\0" or \r.(etc) substring */
00103 /* buf must be erminated by '\0' */
00104 
00105 int pop3_error(char* string);
00106 /* returns 1 if pop server error reply (i.e : -ERR ...) */
00107 
00108 /************************************
00109  * reply re-formatting, after query *
00110  ************************************/
00111 char* nextline(char* string);
00112 /* returns a pointer to the next line of given string */
00113 
00114 char* retr2msg(char* data);
00115 /* returns formatted mail from a pop RETR X query */
00116 /* must only be called on data returned by pop3_retr() */
00117 
00118 void freemsg(char* msg);
00119 /* free the message received by reetr2msg */
00120 
00121 int* list2array(char* poplist);
00122 /* returns an int array of sizes of messages from a LIST pop query */
00123 /* array[0] holds id of the array's last element */
00124 /* must only be called on data received by a pop3_list(sock,0) request */
00125 
00126 void freelistarray(int* array);
00127 /* free the message sizes array created by list2array */
00128 
00129 int listi2size(char* resp);
00130 /* grep the given size (in bytes) in resp after a pop3_list(sock,ID) request */
00131 /* do not use after a pop3_list(sock,0) ! */
00132 
00133 int stat2last(char* resp);
00134 /* returns the number of stored messages on pop server */
00135 
00136 int stat2bytes(char* resp);
00137 /* returns the sumsize in bytes of all stored messages on server */
00138 /* must only be called just after a pop3_stat() request */
00139 
00140 char** uidl2array(char* resp);
00141 /* returns an array of unique strings for each message id */
00142 /* array[0] gives array's last id */
00143 /* must only be called just after a pop3_uidl(sock,0) request */
00144 
00145 void freeuidlarray(char** arrray);
00146 /* free the uidl array created by uidl2array */
00147 
00148 char* uidli2sig(char* resp);
00149 /* grep the pop signature of *one* message signature reply*/
00150 /* should only be called on data received by a pop3_uidl(sock,ID) request */
00151 /* do not use it after a pop3_uidl(sock,0) ! */
00152 
00153 
00154 /***************************************************
00155  * high-level API for a SIMPLE MDA/MUA             *
00156  ***************************************************/
00157 
00158 /******************************************************************************
00159  * This is the high-level API of libspopc and it is recommended to use it     *
00160  * instead of the low-level one. This high-level API, in spite of its very    *
00161  * 'teasing' name, just provides a *very simple* way to access and query a    *
00162  * pop3 server with your e-mail client. This API handles pop3 in a very       *
00163  * convenient manner for the non 'socket-aware' C developper.                 *
00164  ******************************************************************************/
00165 
00166 typedef enum{AUTHORIZATION,TRANSACTION,UPDATE}popstate;
00167 /* pop server states definition from RFC 1725*/
00168 
00169 typedef struct{
00170         int sock;/* socket descriptor */
00171         struct sockaddr_in* connection;
00172         struct hostent* server;
00173         popstate state;/* pop server state */
00174         int* list;/* pop messages size list */
00175         char** uidl;/* pop messages signature list */
00176         int bytes;/* total stored (in bytes) on pop server */
00177         int last;/* last message id */
00178         int del;/* 0|1 flag to ask deletion of retrieved messages */
00179 }popsession;
00180 
00181 #define popbytes(s) ((s)->bytes)
00182 /* gives the total stored data size (in bytes) on the pop server */
00183 /* arg 's' is type 'popsession*'; 'result' is type 'int' */
00184 
00185 #define popnum(s) ((s)->last)
00186 /* gives the number of messages stored on the pop server before any operation */
00187 /* arg 's' is type 'popsession*'; 'result' is type 'int' */
00188 
00189 #define popsetdel(s) ((s)->del=1)
00190 /* asks the session to delete any retrieved messages on the server */
00191 /* arg 's' is type 'popsession*' */
00192 
00193 #define popsetundel(s) ((s)->del=0)
00194 /* asks the session to not delete any retrieved message on the server */
00195 /* arg 's' is type 'popsession*' */
00196 
00197 #define popmsgsize(s,i) ((s)->list[(i)])
00198 /* gives the size of message 'i' for session 's' */
00199 /* args are type 'session*'(s) and 'int'(i) */
00200 /* 'i' must *not* be 0 */
00201 
00202 #define popmsguid(s,i) ((s)->uidl[(i)])
00203 /* points to the 'char*' uid (unique signature) of 'int'(i) message id */
00204 
00205 char* popbegin(const char* servername,const char* user, const char* pass, popsession** sp);
00206 /* prepares, connect and get lists of messages stored on pop server */
00207 /* you must give a valid servername, user and pass */
00208 /* returns an error message if a problem occurs, else NULL */
00209 
00210 char* popgethead(popsession* session, int id);
00211 /* returns the header of a message (id from 1 to popnum()) or NULL if bad id */
00212 
00213 char* popgetmsg(popsession* session, int id);
00214 /* returns a message (id from 1 to popnum()) or NULL if bad id */
00215 
00216 int popdelmsg(popsession* session, int id);
00217 /* deletes message 'id' on pop server */
00218 /* returns -1 if server error, 0 else */
00219 
00220 int popcancel(popsession* session);
00221 /* cancels all previous deletion pn pop server */
00222 /* returns -1 if server error, 0 else */
00223 
00224 void popend(popsession* session);
00225 /* quit and destroys pop session */
00226 
00227 #ifdef __cplusplus
00228 }
00229 #endif
00230 #endif
Generated on Wed Feb 29 22:50:05 2012 for CXXUtilities by  doxygen 1.6.3